apibuilder.json

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "additionalProperties": false,
  "definitions": {
    "apidoc": {
      "title": "API documentation",
      "type": "object",
      "properties": {
        "version": {
          "type": "string",
          "description": "Specifies the version of the API Builder specification that this file is written for. The latest version can be found by visiting /apicollective/apibuilder-spec."
        }
      },
      "required": ["version"],
      "additionalProperties": false
    },
    "info": {
      "title": "contact information",
      "type": "object",
      "properties": {
        "contact": {
          "description": "Specifies contact information for this service.",
          "$ref": "#/definitions/contact"
        },
        "license": {
          "description": "Specifies the license under which this service is released.",
          "$ref": "#/definitions/license"
        }
      },
      "additionalProperties": false
    },
    "contact": {
      "title": "contact information",
      "type": "object",
      "description": "Specifies contact information for this service",
      "properties": {
        "name": {
          "type": "string",
          "description": "Identifying name of the contact person/organization"
        },
        "url": {
          "type": "string",
          "description": "URL pointing to the contact information"
        },
        "email": {
          "type": "string",
          "description": "Email address of the contact person/organization"
        }
      },
      "additionalProperties": false
    },
    "license": {
      "title": "license",
      "type": "object",
      "description": "specifies the license under which this service is released",
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the license - e.g. MIT"
        },
        "url": {
          "type": "string",
          "description": "URL of the license itself"
        }
      },
      "required": ["name"],
      "additionalProperties": false
    },
    "import": {
      "title": "import",
      "type": "object",
      "properties": {
        "uri": {
          "type": "string",
          "description": "The complete URI to the service specification that we are importing. Within API Builder, you can find the URL to the service specification by clicking on the \"service.json\" link for a service."
        }
      },
      "required": ["uri"],
      "additionalProperties": false
    },
    "header": {
      "title": "header",
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "The name of the header."
        },
        "type": {
          "type": "string",
          "description": "The type of this header. Acceptable values are either the name of an enum or string. To specify a collection (meaning multiple values for this header can be provided), the type name can be wrapped with \"[]\". For example, to specify that the type is a collection of strings, use \"[string]\"."
        },
        "required": {
          "type": "boolean",
          "default": true,
          "description": "boolean: true|false. By default, all headers are considered required. To make a parameter optional, set \"required\" to false."
        },
        "default": {
          "description": "The default value for this header. If specified, generated clients will automatically include this header in all requests. Default values must be specified as strings."
        },
        "description": {
          "type": "string",
          "description": "Optional description for what this header provides. Supports GFM."
        },
        "attributes": {
          "type": "array",
          "description": "JSON Array defining additional meta data about this header for use by generators.",
          "items": {
            "$ref": "#/definitions/attribute"
          }
        },
        "deprecation": {
          "$ref": "#/definitions/deprecation"
        }
      },
      "required": ["name", "type"],
      "additionalProperties": false
    },
    "annotation": {
      "title": "annotation",
      "type": "object",
      "patternProperties": {
        "^[a-zA-Z0-9_]*$": {
          "title": "annotation",
          "type": "object",
          "description": "An annotation is just a short key that can be used to tag any field in any model of this API.",
          "properties": {
            "description": {
              "type": "string",
              "description": "Describes what the annotation is used for."
            },
            "deprecation": {
              "$ref": "#/definitions/deprecation"
            }
          },
          "additionalProperties": false
        }
      }
    },
    "attribute": {
      "title": "attribute",
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "the name and identifier of the attribute."
        },
        "value": {
          "title": "json object",
          "type": "object",
          "description": "a JSON object that is usually utilized by a downstream Generator."
        },
        "description": {
          "type": "string"
        }
      },
      "required": ["name", "value"],
      "additionalProperties": false
    },
    "deprecation": {
      "title": "json object",
      "type": "object",
      "description": "JSON Object that indicates that this object is deprecated.",
      "properties": {
        "description": {
          "type": "string",
          "description": "Optional, but recommended to contain notes for what the user is supposed to do now that this property is deprecated. Supports GFM."
        }
      },
      "additionalProperties": false
    },
    "enum": {
      "title": "enumeration",
      "type": "object",
      "patternProperties": {
        "^[a-zA-Z0-9_]*$": {
          "title": "name",
          "type": "object",
          "description": "The name of the enum. Names must be alphanumeric and must start with a letter. Valid characters are a-z, A-Z, 0-9 and _ characters. The name must be unique in the set of names assigned to enums, interfaces, models, or unions types.",
          "properties": {
            "plural": {
              "type": "string",
              "description": "Specifies the optional, plural form of the name. By default, we will pluralize the name using a basic set of english heuristics. The plural is used as a default in cases where it is more natural to specify web services. For example, the default path for a resource will be the plural."
            },
            "description": {
              "type": "string",
              "description": "Optional longer description for this enum."
            },
            "values": {
              "type": "array",
              "description": "JSON Array of EnumValue objects. Each element defines a valid value and an optional description.",
              "items": {
                "$ref": "#/definitions/enumvalues"
              }
            },
            "attributes": {
              "type": "array",
              "description": "JSON Array defining additional meta data about this enum for use by generators.",
              "items": {
                "$ref": "#/definitions/attribute"
              }
            },
            "deprecation": {
              "$ref": "#/definitions/deprecation"
            }
          },
          "required": ["values"],
          "additionalProperties": false
        }
      }
    },
    "enumvalues": {
      "title": "evaluates",
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "The name of the value. Names must start with a letter."
        },
        "value": {
          "type": "string",
          "description": "The actual string representation of this value when serializing. If not specified, defaults to 'name'."
        },
        "description": {
          "type": "string",
          "description": "Optional description for what this enum value provides. Supports GFM."
        },
        "attributes": {
          "type": "array",
          "description": "JSON Array defining additional meta data about this enum value for use by generators.",
          "items": {
            "$ref": "#/definitions/attribute"
          }
        },
        "deprecation": {
          "$ref": "#/definitions/deprecation"
        }
      },
      "required": ["name"],
      "additionalProperties": false
    },
    "interface": {
      "title": "interface",
      "type": "object",
      "patternProperties": {
        "^[a-zA-Z0-9_]*$": {
          "title": "name",
          "type": "object",
          "description": "Name specifies the name of the interface. Names must be alphanumeric and start with a letter. Valid characters are a-z, A-Z, 0-9 and _ characters. The name must be unique in the set of names assigned to enums, interfaces, or models. Note you may define an interface and a union of the same name.",
          "properties": {
            "plural": {
              "type": "string",
              "description": "Specifies the optional, plural form of the name. By default, we will pluralize the name using a basic set of english heuristics. The plural is used as a default in cases where it is more natural to specify web services. For example, the default path for a resource will be the plural."
            },
            "description": {
              "type": "string",
              "description": "Optional description for what this model provides. Supports GFM."
            },
            "fields": {
              "type": "array",
              "description": "JSON Array of 0 or more Fields.",
              "items": {
                "$ref": "#/definitions/field"
              }
            },
            "attributes": {
              "type": "array",
              "description": "JSON Array defining additional meta data about this model for use by generators.",
              "items": {
                "$ref": "#/definitions/attribute"
              }
            },
            "deprecation": {
              "$ref": "#/definitions/deprecation"
            }
          },
          "additionalProperties": false
        }
      }
    },
    "field": {
      "title": "field",
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Specifies the name of the field. Names must be alphanumeric and start with a letter. Valid characters are a-z, A-Z, 0-9 and _ characters.",
          "pattern": "^[a-zA-Z0-9_]*$"
        },
        "type": {
          "type": "string",
          "description": "Specifies the type of this field. Acceptable values include the name of either an enum, a model, or a (primitive type). To specify a List, the type name can be wrapped with \"[]\". For example, to specify that the type is a collection of strings, use \"[string]\". To specify a Map, the type name can be prefixed with \"map[type]\". For example, to specify that the type is a Map of string to long, use \"map[long]\". Note that for map, the keys must be strings (per the JSON specification)."
        },
        "description": {
          "type": "string",
          "description": "Optional description for what this field provides. Supports GFM."
        },
        "required": {
          "type": "boolean",
          "default": true,
          "description": "By default, all fields are considered required. To make a field optional, set \"required\" to false. When a field is marked as required, it must be present in any form of a model for that form to be valid. In client-server scenario, this means that any defaults that are present in the model must be applied by the client. If you want a default to be applied by the receiver, you should mark the field as \"required\": false"
        },
        "default": {
          "description": "Optional default value. The value must be valid for the type specified for this field. For example, if you specify a field named 'limit' with type 'integer', an acceptable default would be 10."
        },
        "example": {
          "type": "string",
          "description": "Optional - an example value for this field used only in the produced documentation"
        },
        "minimum": {
          "type": "integer",
          "description": "Optional - For a string, refers to the minimum length. For an array, the minimum number of elements in the array. For example, a value of 1 for an array would indicate the array must have at least 1 element."
        },
        "maximum": {
          "type": "integer",
          "description": "Optional - For a string, refers to the maximum length. For an array, the maximum number of elements in the array. For example, a value of 1 for an array would indicate the array must have at most 1 element."
        },
        "attributes": {
          "type": "array",
          "description": "JSON Array defining additional meta data about this field for use by generators.",
          "items": {
            "$ref": "#/definitions/attribute"
          }
        },
        "deprecation": {
          "$ref": "#/definitions/deprecation"
        },
        "annotations": {
          "type": "array",
          "description": "JSON Array of type string where each value indicates the name of a declared annotation (optional),",
          "items": {
            "type": "string"
          }
        }
      },
      "required": ["name", "type"],
      "additionalProperties": false
    },
    "model": {
      "title": "model",
      "type": "object",
      "description": "specifies the name of the model. Names must be alphanumeric and start with a letter. Valid characters are a-z, A-Z, 0-9 and _ characters. The name must be unique in the set of names assigned to enums, interfaces, models, or unions types.",
      "patternProperties": {
        "^[a-zA-Z0-9_]*$": {
          "title": "model",
          "type": "object",
          "properties": {
            "description": {
              "type": "string",
              "description": "Description for what this model provides."
            },
            "plural": {
              "type": "string",
              "description": "Specifies the optional, plural form of the name. By default, we will pluralize the name using a basic set of english heuristics. The plural is used as a default in cases where it is more natural to specify web services. For example, the default path for a resource will be the plural."
            },
            "interfaces": {
              "type": "array",
              "description": "JSON Array of type string where each value indicates the name of a declared interface",
              "items": {
                "type": "string"
              }
            },
            "fields": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/field"
              }
            },
            "attributes": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/attribute"
              }
            },
            "deprecation": {
              "$ref": "#/definitions/deprecation"
            }
          }
        }
      },
      "additionalProperties": false
    },
    "union": {
      "title": "union",
      "type": "object",
      "patternProperties": {
        "^[a-zA-Z0-9_]*$": {
          "type": "object",
          "description": "Name specifies the name of the interface. Names must be alphanumeric and start with a letter. Valid characters are a-z, A-Z, 0-9 and _ characters. The name must be unique in the set of names assigned to enums, unions, or models. Note you may define an interface and a union of the same name, but in this case it is required to list that interface in the interfaces field.",
          "properties": {
            "plural": {
              "type": "string",
              "description": "Specifies the optional, plural form of the name. By default, we will pluralize the name using a basic set of english heuristics. The plural is used as a default in cases where it is more natural to specify web services. For example, the default path for a resource will be the plural."
            },
            "discriminator": {
              "type": "string",
              "description": "Specifies an optional, but recommended, name for a type discriminator field which can then be used in serialization / deserialization to identify the type of object. For example, if not specified, a code generator may serialize the union type into a JSON structure of { \"type\" => object }. If a discriminator is provided, the same code generator can flatten the JSON representation to, for example: { \"discriminator\" => \"xxx\", \"field1\" => \"yyy\" }. If provided, the name of the discriminator field must be unique across all of the fields across all of the types of this union."
            },
            "description": {
              "type": "string",
              "description": "Optional description for what this union provides. Supports GFM."
            },
            "interfaces": {
              "type": "array",
              "description": "JSON Array of type string where each value indicates the name of a declared interface",
              "items": {
                "type": "string"
              }
            },
            "types": {
              "type": "array",
              "description": "Specifies the individual types that are part of this union type.",
              "items": {
                "$ref": "#/definitions/uniontype"
              }
            },
            "attributes": {
              "type": "array",
              "description": "JSON Array defining additional meta data about this union for use by generators.",
              "items": {
                "$ref": "#/definitions/attribute"
              }
            },
            "deprecation": {
              "$ref": "#/definitions/deprecation"
            }
          },
          "required": ["types"],
          "additionalProperties": false
        }
      },
      "additionalProperties": false
    },
    "uniontype": {
      "title": "union type",
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "description": "Specifies the type to include in this union type. Acceptable values include the name of either an enum, a model, or a (primitive type).\ndescription optional description for what this type provides. Supports GFM."
        },
        "description": {
          "type": "string"
        },
        "default": {
          "type": "boolean",
          "description": "If true, indicates that this type should be used as the default when deserializing union types. This field is only used by union types that require a discriminator and sets the default value for that discriminator during deserialization."
        },
        "discriminator_value": {
          "type": "string",
          "description": "The discriminator value defines the string to use in the discriminator field to identify this type. If not specified, the discriminator value will default to the name of the type itself."
        },
        "attributes": {
          "type": "array",
          "description": "JSON Array defining additional meta data about this union type for use by generators.",
          "items": {
            "$ref": "#/definitions/attribute"
          }
        },
        "deprecation": {
          "$ref": "#/definitions/deprecation"
        }
      },
      "required": ["type"],
      "additionalProperties": false
    },
    "resource": {
      "title": "resource",
      "type": "object",
      "patternProperties": {
        "^[a-zA-Z0-9_.]*$": {
          "title": "name",
          "type": "object",
          "description": "The name of the model or enum that this resource represents",
          "properties": {
            "path": {
              "type": "string",
              "description": "Optional path where this resource is located. If not provided, defaults to the plural of the typeName, with some assumptions of formatting for web (e.g. lower case, dash separated). Path parameters can be specified by prefixing a path element with ':'. For example, a path of '/:guid' would imply that all operations for this path will require a parameter named 'guid' of type 'string'"
            },
            "description": {
              "type": "string",
              "description": "Optional description for what this resource provides. Supports GFM."
            },
            "operations": {
              "type": "array",
              "description": "One or more operations is required.",
              "items": {
                "$ref": "#/definitions/operation"
              }
            },
            "attributes": {
              "type": "array",
              "description": "JSON Array defining additional meta data about this resource for use by generators.",
              "items": {
                "$ref": "#/definitions/attribute"
              }
            },
            "deprecation": {
              "$ref": "#/definitions/deprecation"
            }
          },
          "required": ["operations"],
          "additionalProperties": false
        }
      },
      "additionalProperties": false
    },
    "operation": {
      "title": "operation",
      "type": "object",
      "description": "",
      "properties": {
        "method": {
          "type": "string",
          "description": "The HTTP method for this operation"
        },
        "path": {
          "type": "string",
          "description": "Optional path for this particular operation. If not provided, defaults to no additional path. Path parameters can be specified by prefixing a path element with ':'. For example, a path of '/:guid' would imply that this operation is available at /resource_path/:guid. Path parameter types are inferred by looking for a field with that name on the model associated with this resource. If not found, the datatype of any path parameter will be string."
        },
        "description": {
          "type": "string",
          "description": "Optional description for what this operation provides. Supports GFM."
        },
        "body": {
          "description": "Optional specification for the type of the body of this request. For all operations that support bodies (e.g. POST, PUT, PATCH), allows you to specify the type of the body.",
          "$ref": "#/definitions/body"
        },
        "parameters": {
          "type": "array",
          "description": "Optional JSON Array of the parameters to this method. By default, for GET methods, parameters are assumed to be in the path or in the query. For other methods, parameters are assumed to be in the path or form body, unless you have explicitly specified a body in which case parameters can be provided in the path or the query.",
          "items": {
            "$ref": "#/definitions/parameter"
          }
        },
        "responses": {
          "description": "Optional JSON Object of HTTP Response Code to Response. If not provided, an HTTP NoContent response is assumed. Only responses for HTTP status codes that are interesting should be documented.",
          "$ref": "#/definitions/response"
        },
        "attributes": {
          "type": "array",
          "description": "JSON array defining additional meta data about this operation for use by generators.",
          "items": {
            "$ref": "#/definitions/attribute"
          }
        },
        "deprecation": {
          "$ref": "#/definitions/deprecation"
        }
      },
      "required": ["method"],
      "additionalProperties": false
    },
    "parameter": {
      "title": "parameter",
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "The name of the parameter. Names must be alphanumeric and must start with a letter. Valid characters are a-z, A-Z, 0-9 and _ characters.",
          "pattern": "^[a-zA-Z0-9_]*$"
        },
        "type": {
          "type": "string",
          "description": "Specifies the type of this parameter. Acceptable values include the name of either an enum, a model, or a (primitive type). To specify a List, the type name can be wrapped with \"[]\". For example, to specify that the type is a collection of strings, use \"[string]\". To specify a Map, the type name can be prefixed with \"map[type]\". For example, to specify that the type is a Map of string to long, use \"map[long]\". Note that for map, the keys must be strings (per the JSON specification)."
        },
        "location": {
          "type": "string",
          "description": "One of: path, query, form, header. Defines the location of this parameter. Default location varies based on the context of the parameter (e.g. if the operation method is a POST, the default will be Form; if a GET, the default will be Query)"
        },
        "description": {
          "type": "string",
          "description": "Optional description for what this parameter provides. Supports GFM."
        },
        "required": {
          "type": "boolean",
          "default": true,
          "description": "By default all parameters are considered required. To make a parameter optional, set \"required\" to false."
        },
        "default": {
          "description": "Optional default value. The value must be valid for the type specified for this parameter. For example, if you specify a parameter named 'limit' with type 'integer', an acceptable default would be 10"
        },
        "example": {
          "type": "string",
          "description": "Optional - an example value for this parameter used only in the produced documentation"
        },
        "minimum": {
          "type": "integer",
          "description": "Optional - For a string, refers to the minimum length. For an array, the minimum number of elements in the array. For example, a value of 1 for an array would indicate the array must have at least 1 element."
        },
        "maximum": {
          "type": "integer",
          "description": "Optional - For a string, refers to the maximum length. For an array, the maximum number of elements in the array. For example, a value of 1 for an array would indicate the array must have at most 1 element."
        },
        "attributes": {
          "type": "array",
          "description": "JSON array defining additional meta data about this parameter for use by generators.",
          "items": {
            "$ref": "#/definitions/attribute"
          }
        },
        "deprecation": {
          "$ref": "#/definitions/deprecation"
        }
      },
      "required": ["name", "type"],
      "additionalProperties": false
    },
    "response": {
      "title": "response",
      "type": "object",
      "patternProperties": {
        "^[0-9]*$": {
          "title": "HTTP status",
          "type": "object",
          "description": "A valid HTTP status code for this response (e.g. 200). Only status codes that have interesting return types should be documented. You can also specify an HTTP status code of 'default' to map to all other non documented types. This is useful to capture a generic error type that would be returned for non documented response codes.\n\nThere are a few conventions enforced:\n- HTTP Response codes of 5xx cannot be explicitly specified and are handled automatically to ensure consistent behavior in generated client libraries.\n- HTTP Response codes of 204 and 304 indicate that no content is returned, so they must use a type of unit.",
          "properties": {
            "type": {
              "type": "string",
              "description": "Specifies the type of this response. Acceptable values include the name of either an enum, a model, or a (primitive type). To specify a List, the type name can be wrapped with \"[]\". For example, to specify that the type is a collection of strings, use \"[string]\". To specify a Map, the type name can be prefixed with \"map[type]\". For example, to specify that the type is a Map of string to long, use \"map[long]\". Note that for map, the keys must be strings (per the JSON specification)."
            },
            "headers": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/header"
              }
            },
            "description": {
              "type": "string",
              "description": "Optional description for what this response provides. Supports GFM."
            },
            "attributes": {
              "type": "array",
              "description": "JSON Array defining additional meta data about this service. Attributes are used to add custom extensions to API Builder and are typically used by generators to enable advanced code generation.",
              "items": {
                "$ref": "#/definitions/attribute"
              }
            },
            "deprecation": {
              "$ref": "#/definitions/deprecation"
            }
          },
          "required": ["type"],
          "additionalProperties": false
        }
      },
      "additionalProperties": false
    },
    "body": {
      "title": "body",
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "description": "Specifies the type of this body. Acceptable values include the name of either an enum, a model, or a (primitive type). To specify a List, the type name can be wrapped with \"[]\". For example, to specify that the type is a collection of strings, use \"[string]\". To specify a Map, the type name can be prefixed with \"map[type]\". For example, to specify that the type is a Map of string to long, use \"map[long]\". Note that for map, the keys must be strings (per the JSON specification)."
        },
        "description": {
          "type": "string",
          "description": "Optional description for what this body provides. Supports GFM."
        },
        "attributes": {
          "type": "array",
          "description": "JSON Array defining additional meta data about this body for use by generators.",
          "items": {
            "$ref": "#/definitions/attribute"
          }
        },
        "deprecation": {
          "$ref": "#/definitions/deprecation"
        }
      },
      "required": ["type"],
      "additionalProperties": false
    }
  },
  "description": "JSON Schema for API Builder's api.json format from https://app.apibuilder.io/doc/apiJson",
  "id": "https://json.schemastore.org/apibuilder.json",
  "properties": {
    "$schema": {
      "type": "string",
      "description": "A JSON schema URL"
    },
    "name": {
      "type": "string",
      "description": "The human readable name of this service. Used for display, and as the basis for generating a unique key for URL."
    },
    "apidoc": {
      "description": "Optionally specify the specific version of API Builder for which your service is written. If not provided, we automatically default to the current production version.",
      "$ref": "#/definitions/apidoc"
    },
    "info": {
      "description": "Optionally specify additional metadata about this service (e.g. contact info, license).",
      "$ref": "#/definitions/info"
    },
    "namespace": {
      "type": "string",
      "description": "Specifies the namespace for this service. Namespace is primarily used when other services import definitions from your service and in the code generators when defining things like package names. If not specified, we will automatically generate a namespace based on [organization namespace].[formatted service name].[major version number]. Note that by default API Builder includes the major version number in the package name which allows service authors and clients to interact with multiple versions of the service where changes have been made in a non backwards compatible way."
    },
    "base_url": {
      "type": "string",
      "description": "The base URL where this service is hosted. Must start with http."
    },
    "description": {
      "type": "string",
      "description": "optional description for what this service provides. Supports GFM."
    },
    "imports": {
      "type": "array",
      "description": "JSON Array defining any other services whose schema definitions we would like to import into our service.",
      "items": {
        "$ref": "#/definitions/import"
      }
    },
    "headers": {
      "type": "array",
      "description": "JSON Array defining any HTTP Headers that the service understands or expects.",
      "items": {
        "$ref": "#/definitions/header"
      }
    },
    "enums": {
      "description": "JSON object defining all of the enums in this API. The key of each object is the enum name.",
      "$ref": "#/definitions/enum"
    },
    "interfaces": {
      "$ref": "#/definitions/interface"
    },
    "models": {
      "description": "JSON object defining all of the models in this API. The key of each object is the model name.",
      "$ref": "#/definitions/model"
    },
    "unions": {
      "$ref": "#/definitions/union"
    },
    "resources": {
      "description": "JSON object defining all of the resources in this API. The key of each object is the name of a type that this resource represents. The type must be the name of a model or an enum.",
      "$ref": "#/definitions/resource"
    },
    "attributes": {
      "type": "array",
      "description": "JSON Array defining additional meta data about this service. Attributes are used to add custom extensions to API Builder and are typically used by generators to enable advanced code generation.",
      "items": {
        "$ref": "#/definitions/attribute"
      }
    },
    "annotations": {
      "description": "JSON object defining all of the annotations in this API. The key of each object is the annotation name.",
      "$ref": "#/definitions/annotation"
    }
  },
  "required": ["name"],
  "title": "API Builder Schema"
}