openapi: "3.0.0"

info:
  title: "{COUNTRY_PACKAGE_NAME} Web API"
  description: "The OpenFisca Web API lets you get up-to-date information and formulas included in the {COUNTRY_PACKAGE_NAME} legislation."
  version: "{COUNTRY_PACKAGE_VERSION}"
  termsOfService: "https://openfisca.org/doc/licence.html"
  contact:
    email: "contact@openfisca.org"
  license:
    name: "AGPL"
    url: "https://www.gnu.org/licenses/agpl-3.0"

tags:
  - name: "Parameters"
    description: "A parameter is a numeric property of the legislation that can evolve over time."
    externalDocs:
      description: "Parameters documentation"
      url: "https://openfisca.org/doc/key-concepts/parameters.html"

  - name: "Variables"
    description: "A variable depends on a person, or an entity (e.g. zip code, salary, income tax)."
    externalDocs:
      description: "Variables documentation"
      url: "https://openfisca.org/doc/key-concepts/variables.html"

  - name: "Entities"
    description: "An entity is a person of a group of individuals (such as a household)."
    externalDocs:
      description: "Entities documentation"
      url: "https://openfisca.org/doc/key-concepts/person,_entities,_role.html"

  - name: "Calculations"

  - name: "Documentation"

components:
  schemas:
    Parameter:
      type: "object"
      properties:
        values:
          $ref: "#/components/schemas/Values"
        brackets:
          type: "object"
          additionalProperties:
            $ref: "#/components/schemas/Brackets"
        subparams:
          type: "object"
          additionalProperties:
            type: "object"
            properties:
              definition:
                type: "string"
        metadata:
          type: "object"
        description:
          type: "string"
        id:
          type: "integer"
          format: "string"
        source:
          type: "string"

    Parameters:
      type: "object"
      additionalProperties:
        type: "object"
        properties:
          description:
            type: "string"
          href:
            type: "string"

    Variable:
      type: "object"
      properties:
        defaultValue:
          type: "string"
        definitionPeriod:
          type: "string"
          enum:
            - "MONTH"
            - "YEAR"
            - "ETERNITY"
        description:
          type: "string"
        entity:
          type: "string"
        formulas:
          type: "object"
          additionalProperties:
            $ref: "#/components/schemas/Formula"
        id:
          type: "string"
        reference:
          type: "array"
          items:
            type: "string"
        source:
          type: "string"
        valueType:
          type: "string"
          enum:
            - "Int"
            - "Float"
            - "Boolean"
            - "Date"
            - "String"

    Variables:
      type: "object"
      additionalProperties:
        type: "object"
        properties:
          description:
            type: "string"
          href:
            type: "string"

    Formula:
      type: "object"
      properties:
        content:
          type: "string"
        source:
          type: "string"

    Brackets:
      type: "object"
      additionalProperties:
        type: "number"
        format: "float"

    Values:
      description: "All keys are ISO dates. Values can be numbers, booleans, or arrays of a single type (number, boolean or string)."
      type: "object"
      additionalProperties:
        $ref: "#/components/schemas/Value"
      # propertyNames:  # this keyword is part of JSON Schema but is not supported in OpenAPI v3.0.0
      # pattern: "^[12][0-9]{3}-[01][0-9]-[0-3][0-9]$"  # all keys are ISO dates

    Value:
      oneOf:
      - type: "boolean"
      - type: "number"
        format: "float"
      - type: "array"
        items:
          oneOf:
          - type: "string"
          - type: "number"

    Entities:
      type: "object"
      properties:
        description:
          type: "string"
        documentation:
          type: "string"
        plural:
          type: "string"
        roles:
          type: "object"
          additionalProperties:
            $ref: "#/components/schemas/Roles"

    Roles:
      type: "object"
      properties:
        description:
          type: "string"
        max:
          type: "integer"
        plural:
          type: "string"

    Trace:
      type: "object"
      properties:
        requestedCalculations:
          type: "array"
          items:
            type: "string"
        entitiesDescription:
          type: "object"
          additionalProperties: false  # Will be dynamically added by the Web API
        trace:
          type: "object"
          additionalProperties:
            type: "object"
            properties:
              value:
                type: "array"
                items: {}
              dependencies:
                type: "array"
                items:
                  type: "string"
              parameters:
                type: "object"
                additionalProperties:
                  type: "object"

  headers:
    Country-Package:
      description: "The name of the country package currently loaded in this API server"
      schema:
        type: "string"

    Country-Package-Version:
      description: "The version of the country package currently loaded in this API server"
      schema:
        type: "string"
        pattern: "^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)(?:-((?:0|[1-9][0-9]*|[0-9]*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9][0-9]*|[0-9]*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$"  # adapted from https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string

paths:
  /calculate:
    post:
      summary: "Run a simulation"
      tags:
      - "Calculations"
      operationId: "calculate"
      requestBody:
        description: "Describe the situation (persons and entities). Add the variable you wish to calculate in the proper entity, with null as the value. Learn more in our official documentation: https://openfisca.org/doc/openfisca-web-api/input-output-data.html"
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SituationInput"
      responses:
        200:
          description: "The calculation result is sent back in the response body"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SituationOutput"
          headers:
            Country-Package:
              $ref: "#/components/headers/Country-Package"
            Country-Package-Version:
              $ref: "#/components/headers/Country-Package-Version"
        404:
          description: "A variable mentioned in the input situation does not exist in the loaded tax and benefit system. Details are sent back in the response body"
          headers:
            Country-Package:
              $ref: "#/components/headers/Country-Package"
            Country-Package-Version:
              $ref: "#/components/headers/Country-Package-Version"
        400:
          description: "The request is invalid. Details about the error are sent back in the response body"
          headers:
            Country-Package:
              $ref: "#/components/headers/Country-Package"
            Country-Package-Version:
              $ref: "#/components/headers/Country-Package-Version"

  /parameters:
    get:
      tags:
      - "Parameters"
      summary: "List all available parameters"
      operationId: "getParameters"
      responses:
        200:
          description: "The list of parameters is sent back in the response body"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Parameters"
          headers:
            Country-Package:
              $ref: "#/components/headers/Country-Package"
            Country-Package-Version:
              $ref: "#/components/headers/Country-Package-Version"

  /parameter/{parameterID}:
    get:
      tags:
      - "Parameters"
      summary: "Get information about a specific parameter"
      operationId: "getParameter"
      parameters:
      - name: "parameterID"
        in: "path"
        description: "ID of parameter. IDs can be obtained by enumerating the /parameters endpoint"
        required: true
        schema:
          type: "string"
      responses:
        200:
          description: "The requested parameter's information is sent back in the response body"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Parameter"
          headers:
            Country-Package:
              $ref: "#/components/headers/Country-Package"
            Country-Package-Version:
              $ref: "#/components/headers/Country-Package-Version"
        404:
          description: "The requested parameter does not exist"
          headers:
            Country-Package:
              $ref: "#/components/headers/Country-Package"
            Country-Package-Version:
              $ref: "#/components/headers/Country-Package-Version"

  /variables:
    get:
      tags:
      - "Variables"
      summary: "List all available variables"
      operationId: "getVariables"
      responses:
        200:
          description: "The list of variables is sent back in the response body"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Variables"
          headers:
            Country-Package:
              $ref: "#/components/headers/Country-Package"
            Country-Package-Version:
              $ref: "#/components/headers/Country-Package-Version"

  /variable/{variableID}:
    get:
      tags:
      - "Variables"
      summary: "Get information about a specific variable"
      operationId: "getVariable"
      parameters:
      - name: "variableID"
        in: "path"
        description: "ID of a variable. IDs can be obtained by enumerating the /variables endpoint."
        required: true
        schema:
          type: "string"
      responses:
        200:
          description: "The requested variable's information is sent back in the response body"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Variable"
          headers:
            Country-Package:
              $ref: "#/components/headers/Country-Package"
            Country-Package-Version:
              $ref: "#/components/headers/Country-Package-Version"
        404:
          description: "The requested variable does not exist"
          headers:
            Country-Package:
              $ref: "#/components/headers/Country-Package"
            Country-Package-Version:
              $ref: "#/components/headers/Country-Package-Version"

  /entities:
    get:
      tags:
      - "Entities"
      summary: "List all available Entities"
      operationId: "getEntities"
      responses:
        200:
          description: "The list of the entities as well as their information is sent back in the response body"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Entities"
          headers:
            Country-Package:
              $ref: "#/components/headers/Country-Package"
            Country-Package-Version:
              $ref: "#/components/headers/Country-Package-Version"

  /trace:
    post:
      summary: "Explore a simulation's steps in details."
      tags:
      - "Calculations"
      operationId: "trace"
      requestBody:
        description: "Describe the situation (persons and entities). Add the variable you wish to calculate in the proper entity, with null as the value."
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SituationInput"
      responses:
        200:
          description: "The calculation details are sent back in the response body"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Trace"
          headers:
            Country-Package:
              $ref: "#/components/headers/Country-Package"
            Country-Package-Version:
              $ref: "#/components/headers/Country-Package-Version"
        404:
          description: "A variable mentioned in the input situation does not exist in the loaded tax and benefit system. Details are sent back in the response body"
          headers:
            Country-Package:
              $ref: "#/components/headers/Country-Package"
            Country-Package-Version:
              $ref: "#/components/headers/Country-Package-Version"
        400:
          description: "The request is invalid. Details about the error are sent back in the response body"
          headers:
            Country-Package:
              $ref: "#/components/headers/Country-Package"
            Country-Package-Version:
              $ref: "#/components/headers/Country-Package-Version"

  /spec:
    get:
      summary: "Provide the API documentation in an OpenAPI format"
      tags:
      - "Documentation"
      operationId: "spec"
      responses:
        200:
          description: "The API documentation is sent back in the response body"
          headers:
            Country-Package:
              $ref: "#/components/headers/Country-Package"
            Country-Package-Version:
              $ref: "#/components/headers/Country-Package-Version"