openapi: 3.0.1
info:
  title: GDSO standard API
  description: This is the description of the Standard API
  termsOfService: https://www.gdso.org/api/documents/file/GDSO-GeneralTermsofUse_Production_FEB2023-(1)-1.pdf
  contact:
    email: info@gdso.org
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 2.1.2
servers:
- url: "{resolvedEndpoint}"
  description: Base URL obtained through ONS resolution of the company prefix
  variables:
    resolvedEndpoint:
      default: https://example.com
      description: Endpoint returned by the ONS resolution for the tyre manufacturer
tags:
- name: tire
  description: Everything about your Tire
  externalDocs:
    description: Find out more
    url: https://gdso-org.github.io/tech-doc/
paths:
  /tire/{sgtin}:
    get:
      tags:
      - tire
      summary: get tire information from a sgtin96 tag
      description: Returns product information related to this individual tire. This
        operation requires authentication.
      operationId: getTireBySgtin
      parameters:
      - name: sgtin
        in: path
        description: serial number of the tire to get information on. It must be an
          existing SGTIN96 serial number in pureId form (urn:epc:id:sgtin:086699.0337140.9413672970)
        required: true
        schema:
          type: string
      - name: country
        in: query
        description: API request's country of origin (ISO 2-digits code)
        schema:
          type: string
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tire'
        "400":
          description: bad request
          content: {}
        "404":
          description: Tire not found / Invalid sgtin supplied
          content: {}
      security:
      - OAuth2:
        - read
  /tires:
    post:
      tags:
      - tire
      summary: Get tire informations from an array of SGTIN-96
      description: Returns product information related to the list of tires available
        in the payload. This operation requires authentication.
      operationId: getTiresByBatch
      requestBody:
        description: "List of UIIs (Limit max : 100)"
        required: true
        content:
          application/json:
            schema:
              type: array
              maxItems: 100
              items:
                type: string
              example: [
                "urn:epc:id:sgtin:086699.0337140.9413672970",
                "urn:epc:id:sgtin:086699.0337140.9413672970",
                "urn:epc:id:sgtin:086699.0337140.9413672970"
              ]
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  oneOf: 
                    - "$ref": "#/components/schemas/TireModelUii"
                    - "$ref": "#/components/schemas/TireNotFoundUii"
        "400":
          description: bad request
          content: {}
        "404":
          description: Tire not found / Invalid sgtin supplied
          content: {}
      security:
      - OAuth2:
        - read
components:
  schemas:
    Labelling:
      type: array
      description: Labelling
      items:
        type: object
        properties:
          noisePerformance:
            type: integer
            description: Labelling noise performance
            example: 70
          noiseClass:
            type: string
            description: Labelling noise class
            example: C4
          rollingResistanceClass:
            type: string
            description: Labelling Rolling Resistance class
            example: B
          wetClass:
            type: string
            description: Labelling wet class
            example: C
          labellingReferenceRegulation:
            type: string
            description: "Regulation to which the labelling level of the tire for\
              \ wet, noise and rolling resistance is given."
            example: EUR DIR 1222/2009
          eprelRecordReferenceUrl:
            type: string
            description: URL to the EPREL record of the tire
            example: https://www.eprel.com/reference/123456
          labelPictureUrl:
            type: string
            description: URL to the label picture
            example: https://www.michelin.com/label/product/123456
    ItemIDS:
      type: object
      properties:
        eanCode:
          type: string
          description: European Article number according to GS1 standard
          example: "3528709789509"
        upcCode:
          type: string
          description: (Private) Universal Product code according to GS1 standard
          example: "00412345678"
      description: various Item/article IDs
    Dimensions:
      type: object
      properties:
        geometricalTyreSize:
          type: string
          description: Tyre size designation
          example: 195/65 R 17
        sectionWidth:
          type: object
          properties:
            value:
              type: number
              description: section width value
              example: 195.0
            uom:
              type: string
              description: unit of measure for section width
              example: MILLIMETER
              enum:
              - MILLIMETER
              - INCH
          description: Nominal section width of the tire
        aspectRatio:
          type: integer
          description: Aspect Ratio
          example: 65
        rimCode:
          type: object
          properties:
            value:
              type: number
              description: Rim diameter
              example: 17.0
            uom:
              type: string
              description: unit of measure for the rim diameter
              example: INCH
              enum:
              - MILLIMETER
              - INCH
      description: dimensions of the tire
    Specifications:
      type: object
      description: specifications of the tire (load index, speed symbol ...)
      properties:
        loadIndex:
          type: integer
          description: Load index
          example: 87
        loadIndexForDualFitment:
          type: integer
          description: Load index for dual fitment
          example: 88
        speedSymbol:
          type: string
          description: Speed symbol
          example: H
        speedSymbolSupplementaryServiceCondition:
          type: string
          description: "For commercial tires, load adjusted speed"
          example: I
        loadIndexSupplementaryServiceCondition:
          type: integer
          description: "For commercial tires, speed adjusted load"
          example: 85
        loadIndexSupplementaryServiceConditionDualFitment:
          type: integer
          description: "For commercial tires, speed adjusted load for dual fitment"
          example: 86
        structure:
          type: string
          description: Structure Radial or Bias
          example: R
          enum:
          - R
          - B
        tubeCharacteristic:
          type: string
          description: It indicates tubeless or tube type tyres
          example: TL
          enum:
          - TT
          - TL
        extraLoadOrReinforced:
          type: boolean
          description: Extra Load symbol to be associated to the load index if needed
          example: true
        directional:
          type: boolean
          description: Directional arrow marking - it indicates the rotation sens
            of the tire
          example: true
        asymetrical:
          type: boolean
          description: It indicates if the tire as a specific mounting sens (OUTSIDE
            marking)
          example: false
        runFlat:
          type: string
          description: It indicates the capability of the tire to run without pressure
          example: E
        sealant:
          type: boolean
          description: It indicates the fact that the tire is equipped with a puncture
            sealant
          example: true
        maxLoadCarryingCapacity:
          type: integer
          description: (Private) Load capacity (kg) per axle at max inflation pressure
            (kPa) and at the specified speed
          example: 1200
        hlpc:
          type: boolean
          description: Indicates if the tire meets the UN R.30 definition of High Load (HL), values according to ETRTO standard
          example: true
    Markings:
      type: object
      properties:
        mudAndSnow:
          type: boolean
          description: Mud and Snow (M+S) marking
          example: true
        "3pmsf":
          type: boolean
          description: 3PMSF marking to indicate if the tire is designed for use in
            severe snow conditions
          example: true
        iceGrip:
          type: boolean
          description: Ice grip marking to indicate the tire performance on ice
          example: true
        tractionTire:
          type: boolean
          description: Traction regulatory marking (UNECE R117) Tires primarly designed
            for the drive axle to maximise torque transmission in various circumstances
          example: true
        freeRollingTire:
          type: boolean
          description: "FRT marking Tire designed for equipment of trailer axles,\
            \ axles of motor vehicles other than front steering and drive axles."
          example: true
        professionnalOfRoad:
          type: boolean
          description: POR marking Tire designed for service in severe off road conditions
          example: true
        sizeSuffix:
          type: string
          description: "Part of identification marking of the tire (see G9 ETRTO Std\
            \ Manual T = temporary, P = Passenger for TRA std, LT = light truck (alternative\
            \ to C Marking of R54)"
          example: CP
          enum:
          - C
          - CP
        sizePrefix:
          type: string
          description: "Part of identification marking of tire (see G9 ETRTO Std Manual\
            \ T = temporary, P, LT or HL)"
          example: T
          enum:
          - T
          - P
          - LT
          - HL
        OEMarking:
          type: array
          items:
            type: object
            properties:
              oemName:
                type: string
                description: Specific original equipment marking - OEM Name
                example: Mercedes
              tireMarking:
                type: string
                description: Specific original equipment marking
                example: MO
        maxInflationPressure:
          type: integer
          description: (Private) Max tyre inflation pressure in kPa
          example: 530
      description: "different markings of the tire (M+S, POR ...)"
    NationalRegulationsCompliances:
      type: array
      description: (Private) Compliance information to national regulations
      items:
        type: object
        properties:
          marking:
            type: string
            description: Regulation name or marking
            example: CCC
    Weight:
      type: object
      properties:
        value:
          type: number
          description: tire weight value
          example: 10.5
        uom:
          type: string
          description: unit of measure for tire weight
          example: KILOGRAM
          enum:
          - KILOGRAM
      description: (Private) weight of the tire
    VectoCoefficient:
      type: object
      properties:
        value:
          type: number
          description: coefficient value
          example: 7.0
        uom:
          type: string
          description: unit of measure for coefficient
          example: N/kN
          enum:
          - N/kN
      description: (Private) DECLARED COEFFICIENT VALUE (N/kN) according to EU 2017/2400
        Regulation
    WltpCoefficient:
      type: object
      properties:
        value:
          type: number
          description: WLTP Tyre Rolling coefficient value
          example: 5.6
        uom:
          type: string
          description: unit of measure for WLTP coefficient
          example: kg/T
          enum:
          - kg/T
      description: (Private) Aligned COEFFICIENT VALUE (N/kN) according to EU 2017/1151
        Regulation
    TyreRollingCircumference:
      type: object
      properties:
        value:
          type: number
          description: Circumference value
          example: 1720.0
        uom:
          type: string
          description: unit of measure for circumference value
          example: MILLIMETER
          enum:
          - MILLIMETER
      description: (Private) Theoretical Tyre Rolling Circumference - Calculated according
        to ETRTO for PC and CV tyres (TRA for LT) and reported in mm
    Tire:
      type: object
      properties:
        uii:
          type: string
          description: (Private) Unique Item Identifier - SGTIN-96 following Pure
            identity EPC URN (GS1 EPCIS) format
          example: urn:epc:id:sgtin:12345678.04444.2222222
        product:
          $ref: '#/components/schemas/Product'
        dotTin:
          type: object
          properties:
            factoryCode:
              type: string
              description: Production zone/plant of the tire
              example: B3
            sizeCode:
              type: string
              description: tire size code
              example: 8U
            optionalCode:
              type: string
              description: tire optional code
              example: 005X
            weekYear:
              type: string
              description: tire production week
              example: "1020"
          description: "(Private) Tire Identification Number (consisting of Plant\
            \ Code, Size Code and Type Code) (US Market )"
        countryOfOrigin:
          type: string
          description: (Private) ISO code on 3 characters that indicates the tire's
            country of origin
          example: ITA
        nationalRegulationsComplianceCode:
          type: number
          description: (Private) Code that indicates compliance of tire to specific
            international legal market requirement based on PRICAT standard
          example: 105.0
        nationalRegulationsCompliances:
          $ref: '#/components/schemas/NationalRegulationsCompliances'
        weight:
          $ref: '#/components/schemas/Weight'
        vectoTyreRollingResistance:
          $ref: '#/components/schemas/VectoCoefficient'
        vectoCertificateNumber:
          type: string
          description: (Private) Certificate number according to EU 2017/2400 Regulation
            format in ASCII
          example: e4*2017/2400*2022/1379*T*01002*00
        rollingCircumference:
          $ref: '#/components/schemas/TyreRollingCircumference'
        wltpTyreRollingResistance:
          $ref: '#/components/schemas/WltpCoefficient'
        developmentIdentifier:
          type: string
          description: (Private) Specification/Identification used during tyre developement.
            Alpha numeric code used by the Stakeholders if applicable in ASCII
          example: A1234568A
        customerPartNumber:
          type: string
          description: (Private) Internal reference for customer Prototype / Series.
            Alpha numeric code used by the OEM if applicable in ASCII
          example: X1Y2-Z
        oemSubmissionIdentifier:
          type: string
          description: "(Private) Id provided by the OEM for specific technical requirements\
            \ submittal during the vehicle / tyre development cycles, so that variants\
            \ for the same specification can be distinguished by them."
          example: A1B2C3...
      xml:
        name: Tire
    Product:
      type: object
      properties:
        itemIDS:
          $ref: '#/components/schemas/ItemIDS'
        commercialNameLongDescription:
          type: string
          description: Marketing text / Commercial name of the product
          example: 195/65 R 17 87H TL Dakota Spring
        brandName:
          type: string
          description: Manufacturer’s name or brand name
          example: Bravetyre
        commercialName:
          type: string
          description: Commercial Name
          example: Dakota Spring
        dimensions:
          $ref: '#/components/schemas/Dimensions'
        specifications:
          $ref: '#/components/schemas/Specifications'
        markings:
          $ref: '#/components/schemas/Markings'
        productType:
          type: string
          description: Marketing appreciation of the targeted product usage based
            on manufacturer classification based on PRICAT standard
          example: "110"
        labelling:
          $ref: '#/components/schemas/Labelling'
        nonGradingEligibility:
          type: boolean
          description: Non grading elegibility according to ??
          example: false
        labelTireClassAssociated:
          type: string
          description: C1 / C2 / C3 tyre
          example: C1
        supplierId:
          type: string
          description: (Private) Supplier Number or Vendor Number assigned to a tyre
            manufacturer by the OEM to identify the company (alphanumeric field)
          example: A1B2C3D4
        urls:
          type: array
          items:
            type: object
            properties:
              website:
                type: string
                description: type of the web site the URL is pointing on
                example: Brand
                enum:
                - Brand
                - Product
              url:
                type: string
                description: URL of the website
                example: http://www.gdso.org
    TireModelUii:
      allOf:     # Combines the BasicErrorModel and the inline model
        - type: object
          required:
            - uii
          properties:
            uii:
              type: string
              example : "urn:epc:id:sgtin:012345.0987654.123456789"
        - type: object
          required:
            - status
          properties:
            status:
              type: integer
              enum:
                - 200
              example : 200
        - $ref: "#/components/schemas/Tire"
    TireNotFoundUii:
      allOf:     # Combines the BasicErrorModel and the inline model
        - type: object
          required:
            - uii
          properties:
            uii:
              type: string
              example : "urn:epc:id:sgtin:012345.0987654.123456790"
        - type: object
          required:
            - status
          properties:
            status:
              type: integer
              enum:
                - 404
              example : 404
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://example.com/oauth/authorize
          tokenUrl: https://example.com/oauth/token
          scopes:
            read: Grants read access