definitions.yaml

#  2022-11-23T11:05:27
info:
  description: |
    OpenAPI 3 templates and definitions for implementing
    interoperable APIs.

    The work is ongoing, your feedback is greatly appreciated!
  title: Interoperability components Italy
  version: master
  x-commit: c498a7383f73372f09bfefcd81fbdef0c7190fa5
  x-date: 1669201527
openapi: 3.0.0
components:
  headers:
    Cache-Control:
      description: |-
        Cache usage SHOULD be extensively detailed in the `description` property
        to avoid data leaks or the usage of stale data.
        This rule should ensure in some way that the api provider
        documented extensively the cache usage to avoid data leaks
        or usage of stale data.
        For now this ruleset tests:
        * the presence of following keywords
          in the `description`: `max-age`, `private`, `no-store`, `no-cache`.
        * that one and only one between Expires and Cache-Control is used.
        `Cache-Control` and `Expires` should not be used in conjuction,
        because `Cache-Control` overrides `Expires` when `max-age` is set.
        Instead if neither `Cache-Control` or `Expires` are set, clients MAY use euristic cache
        like described in RFC7234.
      schema:
        example: no-store
        externalDocs:
          url: https://datatracker.ietf.org/doc/html/rfc7234
        pattern: '[a-zA-Z0-9=;" -]{,255}'
        type: string
    Location:
      description: |-
        In some responses, this header references the
        primary resource created.

        It is used for redirections too.

        See https://tools.ietf.org/html/rfc7231#section-7.1.2
      schema:
        format: url
        maxLength: 4096
        type: string
    Retry-After:
      description: |-
        Retry contacting the endpoint *at least* after seconds.
        See https://tools.ietf.org/html/rfc7231#section-7.1.3
      schema:
        format: int32
        maximum: 186400
        minimum: 0
        type: integer
    Sunset:
      description: The Sunset HTTP response header field, indicates that a URI is
        likely to become unresponsive at a specified point in the future.  It also
        defines a sunset link relation type that allows linking to resources providing
        information about an upcoming resource or service sunset.
      schema:
        example: Sun, 06 Nov 1994 08:49:37 GMT
        externalDocs:
          url: https://tools.ietf.org/html/rfc7231#appendix-D
        format: HTTP-date
        maxLength: 30
        type: string
    X-Content-Type-Options:
      description: |-
        The X-Content-Type-Options response HTTP header indicates
        that the MIME types advertised in the Content-Type headers should not be changed and be followed.
        Site security testers usually expect this header to be set to `nosniff`.
      schema:
        enum:
        - nosniff
        example: nosniff
        externalDocs:
          url: https://fetch.spec.whatwg.org/#x-content-type-options-header
        type: string
    X-RateLimit-Limit:
      description: The number of allowed requests in the current period
      schema:
        format: int32
        maximum: 1000000
        minimum: 0
        type: integer
    X-RateLimit-Remaining:
      description: The number of remaining requests in the current period
      schema:
        format: int32
        maximum: 1000000
        minimum: 0
        type: integer
    X-RateLimit-Reset:
      description: The number of seconds left in the current period
      schema:
        format: int32
        maximum: 186400
        minimum: 0
        type: integer
  parameters:
    Etag:
      description: |
        The RFC7232 ETag header field in a response provides the current entity-
        tag for the selected resource. An entity-tag is an opaque identifier for
        different versions of a resource over time, regardless whether multiple
        versions are valid at the same time. An entity-tag consists of an opaque
        quoted string, possibly prefixed by a weakness indicator.
      example: W/"xy", "5", "7da7a728-f910-11e6-942a-68f728c1ba70"
      in: header
      name: Etag
      required: false
      schema:
        maxLength: 1024
        type: string
    IfMatch:
      description: |
        The RFC7232 If-Match header field in a request requires the server to
        only operate on the resource that matches at least one of the provided
        entity-tags. This allows clients express a precondition that prevent
        the method from being applied if there have been any changes to the
        resource.
      example: '"5", "7da7a728-f910-11e6-942a-68f728c1ba70"'
      in: header
      name: If-Match
      required: false
      schema:
        maxLength: 1024
        type: string
    IfNoneMatch:
      description: |
        The RFC7232 If-None-Match header field in a request requires the server
        to only operate on the resource if it does not match any of the provided
        entity-tags. If the provided entity-tag is `*`, it is required that the
        resource does not exist at all.
      example: '"7da7a728-f910-11e6-942a-68f728c1ba70", *'
      in: header
      name: If-None-Match
      required: false
      schema:
        maxLength: 1024
        type: string
    citizen:
      description: testme
      in: query
      name: citizen
      schema:
        $ref: '#/components/schemas/Person'
    cursor:
      description: An opaque identifier that points to the next item in the collection.
      example: 01BX9NSMKVXXS5PSP2FATZM123
      in: query
      name: cursor
      schema:
        maxLength: 1024
        type: string
    fields:
      description: Fields to retrieve
      in: query
      name: fields
      schema:
        maxLength: 4096
        type: string
    limit:
      description: How many items to return at one time (max 100)
      in: query
      name: limit
      schema:
        format: int32
        maximum: 100
        minimum: 0
        type: integer
    offset:
      description: The zero-ary offset index into the results
      in: query
      name: offset
      schema:
        default: 0
        format: int32
        maximum: 1e10
        minimum: 0
        type: integer
    q:
      description: Search query term
      in: query
      name: q
      schema:
        maxLength: 2048
        type: string
    sort:
      description: Sorting order
      in: query
      name: sort
      schema:
        example: +name
        maxLength: 1024
        type: string
  responses:
    400BadRequest:
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
      description: Bad Request
    404NotFound:
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
      description: Not Found
    429TooManyRequests:
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
      description: Too many requests
      headers:
        Retry-After:
          $ref: '#/components/headers/Retry-After'
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
    503ServiceUnavailable:
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
      description: Service Unavailable
      headers:
        Retry-After:
          $ref: '#/components/headers/Retry-After'
    default:
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
      description: Unexpected error
  schemas:
    Address:
      properties:
        city:
          description: https://w3id.org/italia/onto/CLV/City
          maxLength: 128
          type: string
        country:
          description: https://w3id.org/italia/onto/CLV/Country
          maxLength: 128
          type: string
        province:
          description: https://w3id.org/italia/onto/CLV/Province
          maxLength: 3
          type: string
        region:
          maxLength: 128
          type: string
        zip_code:
          maxLength: 6
          type: string
      required:
      - city
      - province
      - country
      type: object
      x-jsonld-context:
        '@vocab': https://w3id.org/italia/onto/CLV/
        city: hasCity
        country:
          '@context':
            '@base': http://publications.europa.eu/resource/authority/country/
          '@id': hasCountry
          '@type': '@id'
        province:
          '@context':
            '@base': https://w3id.org/italia/data/identifiers/provinces-identifiers/vehicle-code/
          '@id': hasProvince
          '@type': '@id'
        region:
          '@context':
            '@base': https://w3id.org/italia/controlled-vocabulary/territorial-classifications/regions/
          '@id': hasRegion
          '@type': '@id'
        zip_code: postCode
      x-jsonld-type: https://w3id.org/italia/onto/Address
    Amount:
      description: |
        ISO20022: Amount of money to be moved between the debtor and creditor, before deduction of charges, expressed in the currency as ordered by the initiating party.
      example: '12.25'
      maxLength: 35
      minLength: 1
      pattern: ^\-{0,1}[0-9]{1,13}(\.[0-9]{0,5}){0,1}$
      type: string
    Coordinates:
      description: |-
        Geographic coordinates of a point. The names "lat" and "long" are inherited from the clvapit.
        Example URL: http://dati.beniculturali.it/lodview/mibact/luoghi/resource/Geometry/Coordinate_geografiche_della_sede_di_Gallerie_degli_Uffizi_-_Corridoio_Vasariano_20440.html
      properties:
        lat:
          $ref: '#/components/schemas/Latitude'
        long:
          $ref: '#/components/schemas/Longitude'
      required:
      - lat
      - long
    CurrencyCode:
      description: |
        Specifies the currency of the amount or of the account.
        A code allocated to a currency by a Maintenance Agency under an international identification scheme, as described in the latest edition of the international standard ISO 4217 "Codes for the representation of currencies and funds".
      example: EUR
      maxLength: 3
      pattern: ^[A-Z]{3,3}$
      type: string
    Latitude:
      description: |-
        Latitude of a point expressed in:

        * the ETRS89 system for Italian and European territories
        * and in WGS84 for the others.
      example: 45.492599
      externalDocs:
        url: http://dati.gov.it/onto/clvapit#long
      format: double
      maximum: 90
      minimum: -90
      type: number
    LatitudeString:
      description: |-
        Latitude of a point expressed in:

        * the ETRS89 system for Italian and European territories
        * and in WGS84 for the others.

        Value is serialized as a string. The associated numeric value must be
        between -90 and 90.

        The string value is safe from floating-point aritmetic errors.
      example: '45.492599412312331'
      type: string
    Location:
      properties:
        city:
          description: https://w3id.org/italia/onto/CLV/City
          maxLength: 128
          type: string
        country:
          description: https://w3id.org/italia/onto/CLV/Country
          maxLength: 128
          type: string
        province:
          description: https://w3id.org/italia/onto/CLV/Province
          maxLength: 3
          type: string
        region:
          maxLength: 128
          type: string
        zip_code:
          maxLength: 6
          type: string
      required:
      - country
      type: object
      x-jsonld-context:
        '@vocab': https://w3id.org/italia/onto/CLV/
        city: hasCity
        country:
          '@context':
            '@base': http://publications.europa.eu/resource/authority/country/
          '@id': hasCountry
          '@type': '@id'
        province:
          '@context':
            '@base': https://w3id.org/italia/data/identifiers/provinces-identifiers/vehicle-code/
          '@id': hasProvince
          '@type': '@id'
        region:
          '@context':
            '@base': https://w3id.org/italia/controlled-vocabulary/territorial-classifications/regions/
          '@id': hasRegion
          '@type': '@id'
        zip_code: postCode
      x-jsonld-type: https://w3id.org/italia/onto/CLV/Feature
    Longitude:
      description: |-
        Longitude of a point expressed in:

        * the ETRS89 system for Italian and European territories
        * and in WGS84 for the others.
      example: 9.19289
      externalDocs:
        url: http://dati.gov.it/onto/clvapit#long
      format: double
      maximum: 180
      minimum: -180
      type: number
    LongitudeString:
      description: |-
        Latitude of a point expressed in:

        * the ETRS89 system for Italian and European territories
        * and in WGS84 for the others.

        Value is serialized as a string. The associated numeric value must be
        between -180 and 180.

        The string value is safe from floating-point aritmetic errors.
      example: '9.192894141231231'
      type: string
    Money:
      description: |
        An amount of money in a given currency.
      example:
        amount: '12.25'
        currency: EUR
      properties:
        amount:
          $ref: '#/components/schemas/Amount'
        currency:
          $ref: '#/components/schemas/CurrencyCode'
      required:
      - currency
      - amount
      type: object
    Person:
      externalDocs:
        url: https://w3id.org/italia/onto/CPV
      properties:
        birth_place:
          $ref: '#/components/schemas/Location'
        date_of_birth:
          format: date
          type: string
        education:
          maxLength: 3
          type: string
        family_name:
          maxLength: 255
          type: string
        given_name:
          maxLength: 255
          type: string
        residence:
          $ref: '#/components/schemas/Address'
        tax_code:
          $ref: '#/components/schemas/TaxCode'
      type: object
      x-jsonld-context:
        '@vocab': https://w3id.org/italia/onto/CPV/
        birth_place:
          '@context':
            '@vocab': https://w3id.org/italia/onto/CLV/
            city: hasCity
            country:
              '@context':
                '@base': http://publications.europa.eu/resource/authority/country/
              '@id': hasCountry
              '@type': '@id'
            province:
              '@context':
                '@base': https://w3id.org/italia/data/identifiers/provinces-identifiers/vehicle-code/
              '@id': hasProvince
              '@type': '@id'
          '@id': birthPlace
        date_of_birth: dateOfBirth
        education: hasLevelOfEducation
        family_name: familyName
        given_name: givenName
        residence:
          '@context':
            '@vocab': https://w3id.org/italia/onto/CLV/
            city: hasCity
            country:
              '@context':
                '@base': http://publications.europa.eu/resource/authority/country/
              '@id': hasCountry
              '@type': '@id'
            province:
              '@context':
                '@base': https://w3id.org/italia/data/identifiers/provinces-identifiers/vehicle-code/
              '@id': hasProvince
              '@type': '@id'
            region:
              '@context':
                '@base': https://w3id.org/italia/controlled-vocabulary/territorial-classifications/regions/
              '@id': hasRegion
              '@type': '@id'
            zip_code: postCode
          '@id': residentIn
      x-jsonld-type: https://w3id.org/italia/onto/CPV/Person
    Problem:
      additionalProperties: false
      description: |-
        This schema describes RFC7807 Problem Details for HTTP APIs.
        The specification is intentionally flexible, and allows to adapt
        the schema adding further properties, or not enforcing any of the properties
        below.

        To make this schema safe by default, additionalProperties are forbidden though.
        In case you need them, you can either re-define Problem or extend it
        using `allOf`.
      properties:
        detail:
          description: |
            A human readable explanation specific to this occurrence of the
            problem. You MUST NOT expose internal informations, personal
            data or implementation details through this field.

            `detail` supports localized patterns whereas `title` pattern is only in ascii.
          example: Request took too long to complete.
          maxLength: 4096
          pattern: ^.{0,1024}$
          type: string
        instance:
          description: |
            An absolute URI that identifies the specific occurrence of the problem.
            It may or may not yield further information if dereferenced.
          format: uri
          maxLength: 2048
          type: string
        status:
          description: |
            The HTTP status code generated by the origin server for this occurrence
            of the problem.
          example: 503
          exclusiveMaximum: true
          format: int32
          maximum: 600
          minimum: 100
          type: integer
        title:
          description: |
            A short, summary of the problem type. Written in english and readable
            for engineers (usually not suited for non technical stakeholders and
            not localized): the expressed pattern does not support unicode characters.
          example: Service Unavailable
          maxLength: 64
          pattern: ^[ -~]{0,64}$
          type: string
        type:
          default: about:blank
          description: |
            An absolute URI that identifies the problem type.  When dereferenced,
            it SHOULD provide human-readable documentation for the problem type
            (e.g., using HTML).
          example: https://tools.ietf.org/html/rfc7231#section-6.6.4
          format: uri
          maxLength: 2048
          type: string
      type: object
    TaxCode:
      description: Il codice fiscale.
      example: RSSMRA75L01H501A
      externalDocs:
        url: https://w3id.org/italia/onto/CPV/taxCode
      maxLength: 16
      minLength: 11
      pattern: /^(?:(?:[B-DF-HJ-NP-TV-Z]|[AEIOU])[AEIOU][AEIOUX]|[B-DF-HJ-NP-TV-Z]{2}[A-Z]){2}[\dLMNP-V]{2}(?:[A-EHLMPR-T](?:[04LQ][1-9MNP-V]|[1256LMRS][\dLMNP-V])|[DHPS][37PT][0L]|[ACELMRT][37PT][01LM])(?:[A-MZ][1-9MNP-V][\dLMNP-V]{2}|[A-M][0L](?:[1-9MNP-V][\dLMNP-V]|[0L][1-9MNP-V]))[A-Z]$/i
      type: string