Playing around with an API definition format

conference-api.txt

package dev.swiber.api.conference

error Error = NotFound | InternalServerError

[location="/conferences"]
resource Conference {
  [method="GET", location="/{id}"]
  operation Retrieve(RetrieveConference): (ConferenceRetrieved, Error)
  [method="POST"]
  operation Create(CreateConference): (ConferenceCreated, Error)
}

request RetrieveConference {
  location {
    parameters {
      // description: A unique identifier for a conference.
      id {
        type "string"
      }
    }
  }

  example "Retrieve by ID" {
    location {
      parameters {
        id "total-innovation"
      }
    }
  }
}

request CreateConference {
  body {
    content-type "application/json"
    schema ConferenceSchema
    example "Create a new conference" {
      body json`{
        "address": {
          "street": "123 Main St."
        }
      }`
    }
  }
}

response ConferenceRetrieved {
  status 200
  body {
    content-type "application/json"
    schema ConferenceSchema
    example "Retrieve a single conference" {
      body json`{
        "address": {
          "street": "123 Main St."
        }
      }`
    }
  }
}

response ConferenceCreated {
  status 201
}

response NotFound {
  status 404
}

response InternalServerError {
  status 500
}

schema ConferenceSchema json`{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "address": {
      "type": "object",
      "properties": {
        "street": {
          type: "string"
        }
      }
    }
  }
}`