openapi: 3.1.0
info:
  title: DPP API
  version: 2.7.0
  description: |
    The DPP API describes the schema used to render the DPP UI. Maintained by Circulor.
servers:
  - url: https://uat.dpp.circulor.io
    description: Development server
  - url: https://dpp.circulor.io
    description: Production server
paths:
  /api/code/{code}:
    get:
      summary: Fetch a passport by code.
      tags: ["Endpoints"]
      parameters:
        - name: code
          in: path
          description: Passport identifier
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Valid passport response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Passport"
  /api/revalidate/{tag}:
    get:
      tags: ["Endpoints"]
      summary: Purge cached data on-demand for a specific cache tag.
      parameters:
        - name: tag
          in: path
          description: Internal tag used for cached data.
          required: true
          schema:
            type: string
            enum: [passports, auth, prove]
      responses:
        "200":
          description: asdasd
          content:
            application/json:
              schema:
                type: object
                properties:
                  invokedAt:
                    type: string
                    format: date-time
                    description: Timestamp when request was processed
  /api/up:
    get:
      tags: ["Endpoints"]
      summary: Healthcheck.
      responses:
        "200": # status code
          description: Healthy healthcheck response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    properties:
                      invocation:
                        type: string
                        format: uuid
                        description: Unique request reference
                      invokedAt:
                        type: string
                        format: date-time
                        description: Timestamp when request was processed
components:
  schemas:
    Passport:
      type: object
      properties:
        id:
          type: string
          examples: ["m-steel"]
          description: Passport identifier
        name:
          type: string
          examples: ["Steel"]
          description: Passport name
        config:
          $ref: "#/components/schemas/PassportConfig"
        data:
          type: object
          description: Passport data
          additionalProperties:
            $ref: "#/components/schemas/PassportSection"
    PassportConfig:
      type: object
      description: Passport configuration
      properties:
        name:
          type: string
          examples: ["Green Steel"]
          description: Override for passport name if required at org level
        coverage:
          type: array
          items:
            type: string
          examples: ["Product specifications", "Metrics"]
          description: A flag list of datapoints covered
        image_url:
          type: string
          description: Product image URL
        org:
          $ref: "#/components/schemas/PassportOrg"
      required: [org]
    PassportOrg:
      type: object
      description: Organisation object
      properties:
        name:
          type: string
        key:
          type: string
          description: Organsation key, used for theme mapping
        logo_url:
          type: string
          description: Organisation logo URL
    PassportSection:
      type: object
      description: Top-level sections include groupings of subsections
      properties:
        order:
          type: number
          description: Value to order sections by
        slug:
          type: string
          description: URL friendly section name
        description:
          type: string
          description: Detail about the section
      additionalProperties:
        $ref: "#/components/schemas/PassportSubsection"
    PassportSubsection:
      type: object
      description: Subsections are groupings of attributes
      properties:
        type:
          type: string
          enum: [list, table, country_codes_map]
          description: Describes the type of section
        order:
          type: number
          description: Value to order subsections by
        description:
          type: string
        attributes:
          items:
            anyOf:
              - $ref: "#/components/schemas/AttributeString"
              - $ref: "#/components/schemas/AttributeUom"
              - $ref: "#/components/schemas/AttributeLink"
              - $ref: "#/components/schemas/AttributeImage"
              - $ref: "#/components/schemas/AttributeVideo"
      required: [type, order, attributes]
    AttributeString:
      type: object
      properties:
        name:
          type: string
          description: Name of attribute
        description:
          type: string
          description: Description of the attribute (optional)
        mandatory:
          type: boolean
          description: Whether the attribute was required to be provided (optional)
        type:
          type: string
          description: Describes the type of attribute and it's data
        data:
          type: [string, object, array]
          description: Attribute data relevant to the type of attribute
      required: [name, data, type]
    AttributeUom:
      allOf:
        - $ref: "#/components/schemas/AttributeString"
        - type: object
          properties:
            name:
              examples: ["Non-hazardous waste"]
            type:
              type: string
              enum: [uom]
            data:
              type: object
              properties:
                value:
                  type: string
                  examples: ["410.00"]
                uom:
                  type: string
                  examples: ["HBW"]
                  description: Unit of measurement
    AttributeLink:
      allOf:
        - $ref: "#/components/schemas/AttributeString"
        - type: object
          properties:
            name:
              examples: ["Human rights policy"]
            type:
              type: string
              enum: [link]
            data:
              type: object
              properties:
                value:
                  type: string
                  description: URL
                  examples: ["https://circulor.com"]
                label:
                  type: string
                  description: Descriptive label
                  examples: ["View policy"]
              required: [value]
    AttributeImage:
      allOf:
        - $ref: "#/components/schemas/AttributeString"
        - type: object
          properties:
            name:
              examples: ["Internal workings of a non-combustion motorcar"]
            type:
              type: string
              enum: [image]
            data:
              type: object
              properties:
                value:
                  type: string
                  description: URL
                  examples: ["https://placekitten.com/g/200/300"]
                label:
                  type: string
                  description: Descriptive image label
                  examples: ["Kittens"]
              required: [value, label]
    AttributeVideo:
      allOf:
        - $ref: "#/components/schemas/AttributeString"
        - type: object
          properties:
            name:
              examples: ["Responsible sourcing"]
            type:
              type: string
              enum: [video]
            data:
              type: object
              properties:
                value:
                  type: string
                  description: Embed URL
                  examples: ["https://www.youtube.com/embed/-nUv0K7Wmgs"]
                label:
                  type: string
                  description: Descriptive video label
              required: [value, label]
    AttributeLocation:
      allOf:
        - $ref: "#/components/schemas/AttributeString"
        - type: object
          properties:
            name:
              examples: ["Scottish Manufacturing Plant"]
            type:
              type: string
              enum: [location]
            data:
              type: array
              description: List of markers relevant to this location
              items:
                type: object
                properties:
                  coordinates:
                    type: array
                    description: GeoJSON Position [Longitude, Latitude] (optional)
                    examples: [["51.509378", "-0.115807"]]
                  code:
                    type: string
                    description: Two-letter country codes defined by ISO 3166-1 A2
                    examples: ["GB"]
    AttributeGraph:
      allOf:
        - $ref: "#/components/schemas/AttributeString"
        - type: object
          properties:
            type:
              type: string
              enum: [graph]
            data:
              type: object
              description: Collection of nodes and links
              properties:
                nodes:
                  type: array
                  examples: [{id: ID123, name: FacilityOne, root: true, coordinates: ["51.509378", "-0.115807"], meta: ["Cobalt", "Lithium"], scans: ["ScanpointOne"]}]
                  items:
                    type: object
                    properties:
                      id:
                        type: string
                        description: Reference for connecting links
                      name:
                        type: string
                      root:
                        type: boolean
                        description: Set true if this node is the top-level node (no further links)
                      coordinates:
                        type: array
                        description: Latitude and longitude array of node (optional)
                        examples: [["51.509378", "-0.115807"]]
                      timestamp:
                        type: string
                        format: date-time
                        description: Optional timestamp in ISO date format
                      meta:
                        type: array
                        description: Array of metadata string values (optional)
                      scans:
                        type: array
                        description: Array of scanpoint names (optional)
                links:
                  type: array
                  examples: [{source: "ID123", target: "ID234"}]
                  items:
                    type: object
                    properties:
                      source:
                        type: string
                        description: ID of the source node
                      target:
                        type: string
                        description: ID of the target node
    PassportSubsectionTraceability:
      allOf:
        - $ref: "#/components/schemas/PassportSubsection"
        - type: object
          properties:
            type:
              enum: [traceability]
            attributes:
              type: array
              items:
                $ref: "#/components/schemas/AttributeGraph"
    PassportSubsectionCountryCodesMap:
      allOf:
        - $ref: "#/components/schemas/PassportSubsection"
        - type: object
          properties:
            type:
              enum: [country_codes_map]
            attributes:
              type: array
              items:
                $ref: "#/components/schemas/AttributeLocation"
