{
  "$id": "https://firefox-ci-tc.services.mozilla.com/schemas/common/api-reference-v0.json#",
  "$schema": "https://firefox-ci-tc.services.mozilla.com/schemas/common/metadata-metaschema.json#",
  "additionalProperties": false,
  "definitions": {
    "scopeExpressionTemplate": {
      "oneOf": [
        {
          "$ref": "#/definitions/scopeExpressionTemplateString"
        },
        {
          "$ref": "#/definitions/scopeExpressionTemplateAnyOf"
        },
        {
          "$ref": "#/definitions/scopeExpressionTemplateAllOf"
        },
        {
          "$ref": "#/definitions/scopeExpressionTemplateIf"
        },
        {
          "additionalProperties": false,
          "description": "for/each/in objects will replace themselves with an array of basic scopes. They will be flattened into the array this object is a part of.",
          "properties": {
            "each": {
              "pattern": "^[\\x20-\\x7e]*$",
              "type": "string"
            },
            "for": {
              "pattern": "^[a-zA-Z][a-zA-Z0-9_]*$",
              "type": "string"
            },
            "in": {
              "pattern": "^[a-zA-Z][a-zA-Z0-9_]*$",
              "type": "string"
            }
          },
          "required": [
            "for",
            "each",
            "in"
          ],
          "title": "For-All",
          "type": "object"
        }
      ]
    },
    "scopeExpressionTemplateAllOf": {
      "additionalProperties": false,
      "description": "AllOf objects will evaluate to true if all subexpressions are true",
      "properties": {
        "AllOf": {
          "items": {
            "$ref": "#/definitions/scopeExpressionTemplate"
          },
          "type": "array",
          "uniqueItems": true
        }
      },
      "required": [
        "AllOf"
      ],
      "title": "Conjunction",
      "type": "object"
    },
    "scopeExpressionTemplateAnyOf": {
      "additionalProperties": false,
      "description": "AnyOf objects will evaluate to true if any subexpressions are true",
      "properties": {
        "AnyOf": {
          "items": {
            "$ref": "#/definitions/scopeExpressionTemplate"
          },
          "type": "array",
          "uniqueItems": true
        }
      },
      "required": [
        "AnyOf"
      ],
      "title": "Disjunction",
      "type": "object"
    },
    "scopeExpressionTemplateIf": {
      "additionalProperties": false,
      "description": "if/then objects will replace themselves with the contents of then if the `if` is true",
      "properties": {
        "else": {
          "$ref": "#/definitions/scopeExpressionTemplate"
        },
        "if": {
          "pattern": "^[a-zA-Z][a-zA-Z0-9_]*$",
          "type": "string"
        },
        "then": {
          "$ref": "#/definitions/scopeExpressionTemplate"
        }
      },
      "required": [
        "if",
        "then"
      ],
      "title": "Conditional",
      "type": "object"
    },
    "scopeExpressionTemplateString": {
      "description": "The most basic element of a scope expression",
      "pattern": "^[\\x20-\\x7e]*$",
      "title": "Required-Scope",
      "type": "string"
    }
  },
  "description": "Reference of methods implemented by API",
  "metadata": {
    "name": "api",
    "version": 0
  },
  "properties": {
    "$schema": {
      "description": "Link to schema for this reference. That is a link to this very document. Typically used to identify what kind of reference this file is.",
      "format": "uri",
      "title": "Schema Reference",
      "type": "string"
    },
    "apiVersion": {
      "description": "Version of the API",
      "pattern": "^v[0-9]+$",
      "type": "string"
    },
    "description": {
      "description": "API description in markdown",
      "type": "string"
    },
    "entries": {
      "description": "Array of methods in this reference",
      "items": {
        "additionalProperties": false,
        "properties": {
          "args": {
            "description": "Arguments from `route` that must be replaced, they'll appear wrapped in brackets inside `route`.",
            "items": {
              "description": "Argument that appears in `route` warpped in angle brackets. It must be replaced to call the function.",
              "type": "string"
            },
            "type": "array",
            "uniqueItems": true
          },
          "category": {
            "description": "Category for the API method",
            "type": "string"
          },
          "description": {
            "description": "Description (ie. documentation) for the API entry",
            "type": "string"
          },
          "input": {
            "description": "JSON schema for input, if input is validated, otherwise not present. The value must be a relative URI, based on the service's schema location; that is, based at `<rootUrl>/schemas/<serviceName`.",
            "type": "string"
          },
          "method": {
            "description": "HTTP method (verb) used to access the function",
            "enum": [
              "get",
              "post",
              "put",
              "head",
              "delete",
              "options",
              "trace",
              "copy",
              "lock",
              "mkcol",
              "move",
              "purge",
              "propfind",
              "proppatch",
              "unlock",
              "report",
              "mkactivity",
              "checkout",
              "merge",
              "m-search",
              "notify",
              "subscribe",
              "unsubscribe",
              "patch",
              "search"
            ],
            "type": "string"
          },
          "name": {
            "description": "Name of the `function` this is a stable identifier for use in auto-generated client libraries",
            "type": "string"
          },
          "output": {
            "oneOf": [
              {
                "description": "JSON schema for output, if output is validated, otherwise not present. The value must be a relative URI, based on the service's schema location; that is, based at `<rootUrl>/schemas/<serviceName`.",
                "title": "Output Schema",
                "type": "string"
              },
              {
                "description": "Output kind if not JSON matching a specific schema.",
                "enum": [
                  "blob"
                ],
                "title": "Blob",
                "type": "string"
              }
            ],
            "type": "string"
          },
          "query": {
            "description": "List of accepted query-string parameters, these are always optional.",
            "items": {
              "description": "Optional query-string parameter",
              "type": "string"
            },
            "type": "array",
            "uniqueItems": true
          },
          "route": {
            "description": "Route for the call, note that arguments wrapped with brackets, like `/user/<userId>/` must be replaced.",
            "type": "string"
          },
          "scopes": {
            "description": "Scope expression template specifying required scopes for a method. Not provided if authentication isn't required.",
            "oneOf": [
              {
                "$ref": "#/definitions/scopeExpressionTemplateString"
              },
              {
                "$ref": "#/definitions/scopeExpressionTemplateAnyOf"
              },
              {
                "$ref": "#/definitions/scopeExpressionTemplateAllOf"
              },
              {
                "$ref": "#/definitions/scopeExpressionTemplateIf"
              }
            ]
          },
          "stability": {
            "description": "Stability level of the API",
            "enum": [
              "deprecated",
              "experimental",
              "stable"
            ],
            "title": "Stability-Level",
            "type": "string"
          },
          "title": {
            "description": "Title of API entry",
            "type": "string"
          },
          "type": {
            "description": "Type of entry, currently only `function`.",
            "enum": [
              "function"
            ],
            "type": "string"
          }
        },
        "required": [
          "type",
          "method",
          "route",
          "args",
          "name",
          "stability",
          "title",
          "description",
          "category"
        ],
        "title": "API Entry",
        "type": "object"
      },
      "title": "Entries",
      "type": "array",
      "uniqueItems": true
    },
    "serviceName": {
      "description": "Name of service for automation. Will be consumed by client generators to produce URLs",
      "maxLength": 22,
      "minLength": 1,
      "pattern": "^[a-z][a-z0-9_-]*$",
      "type": "string"
    },
    "title": {
      "description": "API title in markdown",
      "type": "string"
    }
  },
  "required": [
    "apiVersion",
    "$schema",
    "title",
    "description",
    "serviceName",
    "entries"
  ],
  "title": "API Reference File",
  "type": "object"
}