pact-openapi-2.2.0.yaml

openapi: 3.1.0
info:
  title: PACT API Specification
  summary: Technical Specifications for PCF Data Exchange (Version 2.2.0)
  version: 2.2.0
  contact: 
    name: WBCSD PACT Project
    url: https://github.com/wbcsd
    email: pact@wbcsd.org
  description: >
    This document describes the technical specifications for the exchange of 
    Product Carbon Footprint (PCF) data between systems. The specification is 
    maintained by the WBCSD PACT project and intended to be used by organizations 
    that wish to exchange PCF data with other organizations. The specifications 
    are designed to be technology-agnostic.
tags:
- name: footprint
  description: Synchronous retrieval of footprints
- name: event
  description: Asynchronous exchange of footprints
servers: 
- url: https://example.com
paths:
  /2/footprints:
    get:
      summary: Action ListFootprints
      description: >
        Retrieve a list of Product Carbon Footprints (PCFs) that are available. 
        The list can be filtered by various criteria.
      operationId: listFootprints
      tags: [footprint]
      parameters:
      - name: limit
        in: query
        schema:
          type: integer
          format: uint
          minimum: 0
      - name: '$filter'
        in: query
        description: Syntax as defined by the ODatav4 specification
        allowEmptyValue: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          headers:
            link:
              description: Link header to next result set. See Tech Specs section 6.6.1
              schema:
                type: string
              example: https://api.example.com/2/footprints?[...]
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ProductFootprint'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - BearerAuth: []
  /2/footprints/{id}:
    get:
      summary: Action GetFootprint
      description: ^
        Retrieve a single Product Carbon Footprint (PCF) by its unique identifier.
      operationId: getFootprintById
      tags: [footprint]
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                description: HTTP Body of Action `GetFootprint`
                type: object
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/ProductFootprint'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - BearerAuth: []
  /2/events:
    post:
      summary: Action Event
      description: >
        Post an event to the system. The event will be processed by the system 
        and may trigger further actions.
      operationId: post_event
      tags: [event]
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PathfinderEvent'
      responses:
        '200':
          description: Success
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '501':
          description: Not implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - BearerAuth: []
components:
  schemas:
    ProductFootprint:
      description: >
        The ProductFootprint is a data type which represents the footprint
        of a product under a specific scope (§ 5.2.1 Scope of a Footprint) 
        and with values calculated in accordance with the PACT Framework.
        
        Conceptually, the data type ProductFootprint is modeled as a multi-purpose 
        container for product-specific emissions factors which is supported by 
        extensibility through Data Model Extensions.

        Each ProductFootprint can and should be updated over time, for instance 
        to incorporate new or refined data from data owners (see § 6 Product 
        Footprint Lifecycle). 
      type: object
      title: ProductFootprint
      required:
      - id
      - specVersion
      - version
      - created
      - status
      - comment
      - companyName
      - companyIds
      - productDescription
      - productIds
      - productCategoryCpc
      - productNameCompany
      - pcf
      properties:
        id:
          description: >
            A unique identifier that a system uses to refer to the entire dataset of the PCF. 
            This is typically an automatically-generated number by the technology solution to maintain 
            the required technical references to data within the system.
            UUID v4 [RFC4122](https://tools.ietf.org/html/rfc4122).
          type: string
          format: uuid
          examples:
            - "f4b1225a-bd44-4c8e-861d-079e4e1dfd69"
        specVersion:
          description: >
            The version of the PACT Tech Specs that the data being shared complies with. 
            This is a string in the format of "major.minor.patch" (e.g. "2.2.0").
          type: string
          pattern: '^\d+\.\d+\.\d+(-\d{8})?$'
          examples:
          - "2.1.0"
        precedingPfIds:
          description: >
            A given PCF may change over time, due to updates to the calculation. 
            This field lists all id's that reflect "past versions" of the current PCF. 
            This is typically an automatically generated field of unique identifiers, 
            maintained by the technology solution.
          type: array
          items:
            type: string
            format: uuid
          minItems: 1
          uniqueItems: true
          examples:
          - ["f4b1225a-bd44-4c8e-861d-079e4e1dfd69","079e425a-464f-528d-341d-4a944a1dfd70"]
        version:
          description: >
            The version number of the PCF; for example starting with 1 and incrementing.
            If changes are made to the PCF, this version number will increment.
          type: integer
          format: int32
          maximum: 2147483647
          minimum: 0
          examples:
          - 1
          - 3303
        created:
          description: >
            The date and time when the PCF was created. This is typically an automatically 
            generated field by the technology solution.
          type: string
          format: date-time
        updated:
          type: string
          format: date-time
          nullable: true
        status:
          description: >
            The status of the PCF. Active means that the PCF is the most recent version 
            and is the one that should be used. Deprecated means that the PCF is no longer 
            the most recent version and should not be used. 
            This attribute typically will be automatically generated by the technology 
            system and will not need to be entered by the user.
          type: string
          enum:
            - Active
            - Deprecated
        statusComment:
          type: string
          nullable: true          
          description: >
            A descriptive reasoning explaining the current status of the PCF, what was 
            changed since the last version, etc.
        validityPeriodStart:
          description: >
            The start date and time of the validity period. The period of time between the 
            validityPeriodStart and validityPeriodEnd is defined as the "validity period", 
            and represents the time period during which the PCF is valid. Specifying the 
            validity period is optional. If this is not specified, then it is assumed the 
            PCF is valid for 3 years, beginning with the referencePeriodEnd. 
          type: string
          format: date-time
          nullable: true
        validityPeriodEnd:
          description: >
            The end date and time of the validity period. See validityPeriodStart for more details.
          type: string
          format: date-time
          nullable: true
        companyName:
          description: >
            The (legal) name of the company supplying the product and reporting the PCF (aka the data owner)
          $ref: '#/components/schemas/NonEmptyString'
        companyIds:
          description: >
            A list of company identifiers which represent the companies that are considered 
            data owners of the provided PCF. In a large organization, this may include multiple
            subsidiaries or legal entities of a given corporation, hence the need to provide 
            multiple identifiers. A list of only one identifier is also valid. The format 
            of each companyID must be provided as a URN (Uniform Resource Name), which 
            helps ensure the data provided is standardized and can be interpreted by the 
            receiving system.
          type: array
          minItems: 1
          uniqueItems: true
          items:
            $ref: '#/components/schemas/Urn'
        productDescription:
          description: >
            A description of the product, including any additional relevant information 
            such as production technology, packaging, feedstock and technical parameters.
          type: string
        productIds:
          description: >
            All relevant product identifiers to identify the product for which the provided 
            PCF was calculated (e.g. supplier part number, GTIN, article number, CPC 
            classification, CAS Number, BOM Version, batch number, etc.)
          type: array
          minItems: 1
          uniqueItems: true
          items:
            $ref: '#/components/schemas/Urn'
        productCategoryCpc:
          description: >
            The UN Central Product Classification Code (CPC) for the given product. The relevant 
            CPC code may be identified here https://unstats.un.org/unsd/classifications/Econ/cpc 
            Advisement: This property will become optional in v3
          $ref: '#/components/schemas/NonEmptyString'
        productNameCompany:
          description: >
            The trade name of the product in order for it to be recognizable by the receiver of the PCF information
          $ref: '#/components/schemas/NonEmptyString'
        comment:
          description: >
            Any additional information related to the PCF. Whereas the property productDescription 
            contains product-level information, comment should be used for information and instructions 
            related to the calculation of the PCF, or other information which informs the ability to interpret
            (e.g. LUC not included as unable to calculate LUC), to audit or to verify the PCF          
            Advisement: This property will become OPTIONAL in version 3 of the Technical Specifications.
          type: string
        pcf:
          $ref: '#/components/schemas/CarbonFootprint'
    NonEmptyString:
      type: string
      minLength: 1
    Urn:
      type: string
      pattern: '^([uU][rR][nN]):'
    CarbonFootprint:
      description: ^
        The CarbonFootprint represents the carbon footprint of a product and related data 
        in accordance with the PACT Framework.
      title: CarbonFootprint
      type: object
      required:
      - declaredUnit
      - unitaryProductAmount
      - referencePeriodStart
      - referencePeriodEnd
      - pCfExcludingBiogenic
      - fossilGhgEmissions
      - fossilCarbonContent
      - biogenicCarbonContent
      - characterizationFactors
      - ipccCharacterizationFactorsSources
      - crossSectoralStandardsUsed
      - boundaryProcessesDescription
      - exemptedEmissionsPercent
      - exemptedEmissionsDescription
      - packagingEmissionsIncluded
      properties:
        declaredUnit:
          description: >
            The unit with which the PCF was calculated 
          type: string
          enum:
            - liter
            - kilogram
            - cubic meter
            - kilowatt hour
            - megajoule
            - ton kilometer
            - square meter
        unitaryProductAmount:
          description: >
            The amount of Declared Units contained within the product to which the PCF refers to. 
            This is not representing the total annual quantity supplied (e.g. if the product is 
            supplied in bulk in kg, which is the declared unit selected, please enter 1)   
          x-pact-unit: declared unit       
          $ref: '#/components/schemas/PositiveNonZeroDecimal'
        pCfExcludingBiogenic:
          description: >
            The PCF of the product excluding biogenic CO2 emissions.
          x-pact-unit: kgCO2e/declared unit
          $ref: '#/components/schemas/PositiveOrZeroDecimal'
        pCfIncludingBiogenic:
          description: >
            The PCF of the product including ALL biogenic emissions (CO2 and otherwise).
          x-pact-unit: kgCO2e/declared unit
          $ref: '#/components/schemas/Decimal'
        fossilGhgEmissions:
          description: >
            The emissions from fossil sources as a result of fuel combustion, from fugitive 
            emissions, and from process emissions. 
          x-pact-unit: kgCO2e/declared unit
          $ref: '#/components/schemas/PositiveOrZeroDecimal'
        fossilCarbonContent:
          description: >
            The fossil carbon content of the product (mass of carbon).
          x-pact-unit: kgC/declared unit
          $ref: '#/components/schemas/PositiveOrZeroDecimal'
        biogenicCarbonContent:
          description: >
            The biogenic carbon content of the product (mass of carbon).
          x-pact-unit: kgC/declared unit
          $ref: '#/components/schemas/PositiveOrZeroDecimal'
        dLucGhgEmissions:
          description: >
            The emissions from land use change (LUC) activities.Emissions resulting from 
            recent (i.e., previous 20 years) carbon stock loss due to land conversion directly 
            on the area of land under consideration. The value of this property MUST include 
            direct land use change (dLUC) where available, otherwise statistical land use 
            change (sLUC) can be used.
          x-pact-unit: kgCO2e/declared unit
          $ref: '#/components/schemas/PositiveOrZeroDecimal'
        landManagementGhgEmissions:
          description: >
            GHG emissions and removals associated with land-management-related changes, 
            including non-CO2 sources.
          x-pact-unit: kgCO2e/declared unit
          $ref: '#/components/schemas/PositiveOrZeroDecimal'
        otherBiogenicGhgEmissions:
          description: >
            All other biogenic GHG emissions associated with product manufacturing and transport 
            that are not included in dLUC (dLucGhgEmissions), iLUC (iLucGhgEmissions), and land 
            management (landManagementGhgEmissions). 
          x-pact-unit: kgCO2e/declared unit
          $ref: '#/components/schemas/PositiveOrZeroDecimal'
        iLucGhgEmissions:
          description: >
            Emissions resulting from recent (i.e., previous 20 years) carbon stock loss due to 
            land conversion on land not owned or controlled by the company or in its supply 
            chain, induced by change in demand for products produced or sourced by the company.
          x-pact-unit: kgCO2e/declared unit
          $ref: '#/components/schemas/PositiveOrZeroDecimal'
        biogenicCarbonWithdrawal:
          description: >
            The Biogenic Carbon contained in the product converted to kilogram of CO2e.
          x-pact-unit: kgCO2e/declared unit
          $ref: '#/components/schemas/NegativeOrZeroDecimal'
        aircraftGhgEmissions:
          description: >
            The GHG emissions resulting from aircraft engine usage for the transport of the
            product, excluding radiative forcing.
          x-pact-unit: kgCO2e/declared unit
          $ref: '#/components/schemas/PositiveOrZeroDecimal'
        characterizationFactors:
          description: >
            The IPCC (Intergovernmental Panel of Climate Change) frequently releases (GWP) 
            global warming potential values for climate gases related to CO2. These GWP 
            values are released in Assessment Reports (AR), which are numbered. The AR 
            umber can be used to track the age and accuracy of the GWP values used in 
            reporting. This field indicates the IPCC version of the GWP characterization 
            factors used in the calculation of the PCF.
            Advisement: This property is DEPRECATED and only kept to ensure backwards-compatibility. It will be removed in version 3 of these Technical Specifications. It does not replace the (also mandatory) property <{CarbonFootprint/ipccCharacterizationFactorsSources}>.
          deprecated: true
          type: string
          enum:
            - AR6
            - AR5
        ipccCharacterizationFactorsSources:
          type: array
          items:
            type: string
            pattern: '^AR\d+$'
          minItems: 1
          uniqueItems: true
        crossSectoralStandardsUsed:
          type: array
          items:
            type: string
            enum:
              - GHG Protocol Product standard
              - ISO Standard 14067
              - ISO Standard 14044
          minItems: 1
          uniqueItems: true
        productOrSectorSpecificRules:
          description: >
            The product-specific or sector-specific rules applied for calculating or 
            allocating GHG emissions. Sector specific guidance frameworks, such as 
            Product Category Rules (PCR), are sets of rules for how to calculate and 
            document Life Cycle Assessments. They provide product category specific
            guidance and enhance comparability between assessments of the different 
            suppliers for the same category (sector). The same applies to Product 
            Environmental Footprint Category Rules (PEFCR)).  If no rules were used, 
            leave this field empty.
          type: array
          items:
            $ref: '#/components/schemas/ProductOrSectorSpecificRule'
          minItems: 1
          uniqueItems: true
        biogenicAccountingMethodology:
          description: >
            Name of the standard followed to account for biogenic emissions and removals.
          type: string
          enum:
            - PEF
            - ISO
            - GHGP
            - Quantis
        boundaryProcessesDescription:
          description: >  
            Brief description of the processes attributable to each life cycle stage included 
            in the PCF (e.g. electricity consumption for manufacturing), especially those 
            that significantly contribute manufacturing steps of the product (including 
            general description of used technologies).
            Advisement: This property will become OPTIONAL in version 3 of the Technical Specifications.
          type: string
        referencePeriodStart:
          description: >
            The start date and time of the earliest activity data used to calculate the 
            PCF. This start date can be considered the start of the period over which 
            the given PCF is referencing, or reporting on.
          type: string
          format: date-time
        referencePeriodEnd:
          description: >
            The end date and time of the latest activity data used to calculate the PCF. 
            This end date can be considered the end of the period over which the given 
            PCF is referencing, or reporting on.
          type: string
          format: date-time
        geographyRegionOrSubregion:
          description: >
            The geographic representation of the PCF may be reported at different 
            levels of granularity, depending on the prefere of the data provider 
            (e.g., at a plant, region, or country level). This attribute specifies 
            the geographic region to which the PCF refers, i.e. "Africa", 
            "Central Asia", etc.
          type: string
          enum:
            - Africa
            - Americas
            - Asia
            - Europe
            - Oceania
            - Australia and New Zealand
            - Central Asia
            - Eastern Asia
            - Eastern Europe
            - Latin America and the Caribbean
            - Melanesia
            - Micronesia
            - Northern Africa
            - Northern America
            - Northern Europe
            - Polynesia
            - South-eastern Asia
            - Southern Asia
            - Southern Europe
            - Sub-Saharan Africa
            - Western Asia
            - Western Europe
        geographyCountry:
          description: >
            The geographic representation of the PCF may be reported at different levels
            of granularity, depending on the prefere of the data provider (e.g., at a 
            plant, region, or country level). This field indicates the country to which 
            the PCF refers. The country name must be according to ISO 3166-2 alpha-2 
            country code (https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
          type: string
          pattern: '^[A-Z]{2}$'
          comment: ISO 3166-1 alpha-2
          examples:
            - US
            - DE
        geographyCountrySubdivision:
          description: >
            The geographic representation of the PCF may be reported at different 
            levels of granularity, depending on the prefere of the data provider 
            (e.g., at a plant, region, or country level). This attribute represents 
            the most granular (i.e. "most specific") geography, i.e. the specific 
            subdivision within a given country, for example New York State within 
            the USA. Follows ISO 3166-2.
          type: string
          pattern: '^[A-Z]{2}-[A-Z0-9]{1,3}$'
          comment: ISO 3166-2
          examples:
            - US-CA
            - DE-BW
        secondaryEmissionFactorSources:
          description: >
            The list of secondary data sources and versions which have been used by 
            you or by suppliers (e.g. data bases such as ecoinvent) for the PCF 
            calculation
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/EmissionFactorDS'
        exemptedEmissionsPercent:
          description: >
            Percentage of emissions EXCLUDED from the cradle to gate PCF in total. 
            The percentage MUST be expressed as a decimal number, and SHOULD comply 
            with the Framework (a maximum of 5% of the cradle to gate PCF emissions 
            may be excluded) as well as any relevant sector specific guidelines 
            referring to exemption rules/cut-off criteria.
            Advisement: The upper boundary of this property (currently `5`) will be removed in version 3 of the Technical Specifications.
          $ref: '#/components/schemas/Percent'
          maximum: 5
        exemptedEmissionsDescription:
          description: >
            If emissions exempted, rationale behind exclusion of specific PCF emissions.
          Advisement: This property will become OPTIONAL in version 3 of the Technical Specifications.
          type: string
        packagingEmissionsIncluded:
          description: >
            True or False to indicate whether packaging emissions are including in the PCF.
          type: boolean
        packagingGhgEmissions:
          description: >
            Emissions resulting from the packaging of the product. The value MUST NOT 
            be defined if packagingEmissionsIncluded is False.
          $ref: '#/components/schemas/PositiveOrZeroDecimal'
          x-pact-unit: kgCO2e/declared unit
        allocationRulesDescription:
          description: >
            Description of the allocation rules applied to the PCF's foreground data 
            including an explanation of the underlying reasons (way of allocating 
            all activities from your manufacturing steps to the declared unit).
          type: string
          nullable: true
        uncertaintyAssessmentDescription:
          description: >
            Results, key drivers, and a short qualitative description of the 
            uncertainty assessment, if applicable.
          type: string
          nullable: true
        primaryDataShare:
          description: >
            Share of primary data in the final PCF, calculated according to 
            the Framework.
          $ref: '#/components/schemas/Percent'
        dqi:
          description: >
            Data Quality Indicators (dqi) in accordance with the Framework. 
          $ref: '#/components/schemas/DataQualityIndicators'
        assurance:
          description: >
            If present, the Assurance information in accordance with Framework.
          $ref: '#/components/schemas/Assurance'
          nullable: true

    PositiveNonZeroDecimal:
      type: string
      pattern: '^(\\d*[1-9]\\d*([\\.]\\d+)?|\\d+(\\.\\d*[1-9]\\d*)?)$'
      comment: A decimal number > 0.
    PositiveOrZeroDecimal:
      type: string
      pattern: '^\\d+(\\.\\d+)?$'
      comment: A decimal number >= 0.
    Decimal:
      type: string
      pattern: '^-?\\d+(\\.\\d+)?$'
    NegativeOrZeroDecimal:
      type: string
      pattern: '^(-\\d+(\\.\\d+)?)|0$'
      comment: A decimal number <= 0.
    ProductOrSectorSpecificRule:
      type: object
      required:
      - operator
      - ruleNames
      properties:
        operator:
          description: >
            Selection of operator of PCR being used for the PCF calculation. If 
            operator is not available in the given list, or if you have followed
            a sector specific guidance, please select "Other" and include details 
            under "otherOperatorName".
          type: string
          enum:
            - PEF
            - EPD International
            - Other
        ruleNames:
          description: >
            Names of the product or sector specific rules being used for the PCF 
            calculation.
          type: array
          items:
            type: string
            minLength: 1
          minItems: 1
          uniqueItems: true
        otherOperatorName:
          description: >
            If operator is Other, then this attribute must be populated with the name 
            of the operator.
          type: string
          minLength: 1
    EmissionFactorDS:
      type: object
      required:
      - name
      - version
      properties:
        name:
          description: >
            Name of the secondary emission factor databases
          $ref: '#/components/schemas/NonEmptyString'
        version:
          description: >
            Version of the secondary emission factor databases
          $ref: '#/components/schemas/NonEmptyString'
    Percent:
      type: number
      format: double
      minimum: 0
      maximum: 100
    DataQualityIndicators:
      description: Data Type "DataQualityIndicators" of Spec Version 2
      title: DataQualityIndicators
      type: object
      required:
      - coveragePercent
      - technologicalDQR
      - temporalDQR
      - geographicalDQR
      - completenessDQR
      - reliabilityDQR
      properties:
        coveragePercent:
          description: >
            Percentage of PCF included in the data quality assessment based on 
            the >5% emissions threshold.
          $ref: '#/components/schemas/Percent'
        technologicalDQR:
          description: >
            Quantitative data quality rating (DQR) based on the data quality matrix
            (Framework Table 9), scoring the technological representativeness of the 
            sources used for PCF calculation based on weighted average of all inputs 
            representing >5% of PCF emissions.
          $ref: '#/components/schemas/FloatBetween1And3'
        temporalDQR:
          description: >
            Quantitative data quality rating (DQR) based on the data quality matrix 
            (Framework Table 9), scoring the temporal representativeness of the sources 
            used for PCF calculation based on weighted average of all inputs 
            representing >5% of PCF emissions.
          $ref: '#/components/schemas/FloatBetween1And3'
        geographicalDQR:
          description: >
            Quantitative data quality rating (DQR) based on the data quality matrix 
            (Framework Table 9), scoring the geographical representativeness of the 
            sources used for PCF calculation based on weighted average of all inputs 
            representing >5% of PCF emissions.
          $ref: '#/components/schemas/FloatBetween1And3'
        completenessDQR:
          description: >
            Quantitative data quality rating (DQR) based on the data quality matrix 
            (Framework Table 9), scoring the completeness of the data collected for 
            PCF calculation based on weighted average of all inputs representing 
            >5% of PCF emissions.
          $ref: '#/components/schemas/FloatBetween1And3'
        reliabilityDQR:
          description: >
            Quantitative data quality rating (DQR) based on the data quality matrix 
            (Framework Table 9), scoring the reliability of the data collected for 
            PCF calculation based on weighted average of all inputs representing 
            >5% of PCF emissions.
          $ref: '#/components/schemas/FloatBetween1And3'
    FloatBetween1And3:
      type: number
      format: float
      maximum: 3
      minimum: 1
    Assurance:
      description: Data Type "Assurance" of Spec Version 2
      title: Assurance
      type: object
      required:
      - assurance
      - providerName
      properties:
        assurance:
          description: >
            True or False to indicate whether the PCF has been assured in line with the Framework.
          type: boolean
        coverage:
          description: >
            Level of granularity of the emissions data assured
          type: string
          enum:
            - corporate level
            - product line
            - PCF system
            - product level
        level:
          description: >
            Level of assurance applicable to the PCF
          type: string
          enum:
            - limited
            - reasonable
          nullable: true
        boundary:
          description: >
            Boundary of the assurance
          type: string
          enum:
          - Gate-to-Gate
          - Cradle-to-Gate
          nullable: true
        providerName:
          description: >
            Name of the independent third party engaged to undertake assurance
            Advisement: Given this property was incorrectly and unintentionally published in V2 of the Technical Specifications as Mandatory, it will be reverted to Optional in version 3 of the Technical Specifications.
          type: string
        completedAt:
          description: >
            The date at which the assurance was completed
          type: string
          format: date-time
          nullable: true
        standardName:
          description: >
            Name of the standard against which the PCF was assured
          type: string
          nullable: true
        comments:
          description: >
            Any additional comments that will clarify the interpretation of the assurance.
          type: string
          nullable: true

    # -----------
    # Event Types
    PathfinderEvent:
      description: possible contents of `data` property of events - see tech specs
        section 6 for details
      type: object
      oneOf:
      - description: "the contents of the `data` field of a `PF Update Event` - see
          Tech Specs section 6.8.3"
        type: object
        required:
        - data
        - type
        properties:
          type:
            type: string
            enum:
            - org.wbcsd.pathfinder.ProductFootprint.Published.v1
          data:
            $ref: '#/components/schemas/PFUpdateEventBody'
      - description: "the contents of the `data` field of a `PF Request Event` – see
          Tech Specs section 6.8.4.1"
        type: object
        required:
        - data
        - type
        properties:
          type:
            type: string
            enum:
            - org.wbcsd.pathfinder.ProductFootprintRequest.Created.v1
          data:
            $ref: '#/components/schemas/PFRequestEventBody'
      required:
      - id
      - source
      - specversion
      - time
      properties:
        specversion:
          type: string
        id:
          type: string
        source:
          type: string
        time:
          type: string
          format: date-time
    PFUpdateEventBody:
      type: object
      required:
      - pfIds
      properties:
        pfIds:
          type: array
          items:
            type: string
            format: uuid
    PFRequestEventBody:
      type: object
      required:
      - pf
      properties:
        pf: {}
        comment:
          type: string
          nullable: true    
    # ---------------
    # Error Responses
    ErrorResponse:
      title: ErrorResponse
      description: Response with an error code and descripton. See Chapter "Error
        Codes" of the Tech Specs for more details.
      type: object
      properties:
        code:
          type: string
          enum:
            - BadRequest
            - NotImplemented
            - AccessDenied
            - NoSuchFootprint
            - TokenExpired
            - InternalError
        message:
          type: string
      required:
      - code
      - message
  securitySchemes:
    BearerAuth:
      description: OAuth2 Client Credentials Grant (RFC6749 4.4)
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: '/auth/token'
          scopes:
            footprint:list: Ability to list footprints
            footprint:read: Ability to access individual footprints