diff --git a/pact-openapi-2.1.0.yaml b/pact-openapi-2.1.0.yaml new file mode 100644 index 0000000..215eeed --- /dev/null +++ b/pact-openapi-2.1.0.yaml @@ -0,0 +1,931 @@ +openapi: 3.1.0 +info: + title: PACT API Specification + summary: Technical Specifications for PCF Data Exchange (Version 2.1.0) + version: 2.1.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. +paths: + /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: [] + /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: [] + /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 + 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.1.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 + $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 + 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 + - productOrSectorSpecificRules + 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. + Note: version 1 did not explictly include non-CO2 sources. This is now included in the definition. + 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). + Note: version 1.0.0 incorrectly defined this is "all other GHG emissions"; i.e. missing the "biogenic" qualifier. + 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: The set of characterization factor identifiers will likely change in future revisions. It is recommended to account for this when implementing the validation of this property. + + type: string + enum: + - AR6 + - AR5 + 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). + 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. + $ref: '#/components/schemas/Percent' + maximum: 5 + exemptedEmissionsDescription: + description: > + If emissions exempted, rationale behind exclusion of specific PCF emissions. + 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 + 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 diff --git a/pact-openapi-2.2.0.yaml b/pact-openapi-2.2.0.yaml index 3f4d8ac..a2d43a1 100644 --- a/pact-openapi-2.2.0.yaml +++ b/pact-openapi-2.2.0.yaml @@ -212,26 +212,33 @@ components: 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. + 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. @@ -240,6 +247,9 @@ components: 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 @@ -320,7 +330,7 @@ components: 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 - Given feedback this code is not commonly used, this attribute will become optional in v3 + Advisement: This property will become optional in v3 $ref: '#/components/schemas/NonEmptyString' productNameCompany: description: > @@ -332,6 +342,7 @@ components: 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' @@ -458,6 +469,7 @@ components: 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: @@ -510,6 +522,7 @@ components: 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: > @@ -599,11 +612,13 @@ components: 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: > @@ -733,35 +748,40 @@ components: (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/PositiveNonZeroDecimal' + $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/PositiveNonZeroDecimal' + $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/PositiveNonZeroDecimal' + $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/PositiveNonZeroDecimal' + $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/PositiveNonZeroDecimal' + $ref: '#/components/schemas/FloatBetween1And3' + FloatBetween1And3: + type: number + format: float + maximum: 3 + minimum: 1 Assurance: description: Data Type "Assurance" of Spec Version 2 title: Assurance @@ -802,6 +822,7 @@ components: 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: > diff --git a/pact-openapi-2.3.0.yaml b/pact-openapi-2.3.0.yaml index 8823f49..380a774 100644 --- a/pact-openapi-2.3.0.yaml +++ b/pact-openapi-2.3.0.yaml @@ -10,9 +10,9 @@ info: 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 + 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. + are designed to be technology-agnostic. servers: - url: https://dev.wbcsd.org/pact/2 description: Development server @@ -183,7 +183,7 @@ components: 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. + and with values calculated in accordance with the PACT Methodology. Conceptually, the data type ProductFootprint is modeled as a multi-purpose container for product-specific emissions factors which is supported by @@ -214,26 +214,33 @@ components: 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.1"). + This is a string in the format of "major.minor.patch" (e.g. "2.3.0"). type: string pattern: '^\d+\.\d+\.\d+(-\d{8})?$' + examples: + - "2.3.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. + 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. @@ -241,6 +248,9 @@ components: type: integer format: int32 minimum: 0 + examples: + - 1 + - 3303 created: description: > The date and time when the PCF was created. This is typically an automatically @@ -305,7 +315,9 @@ components: productDescription: description: > A description of the product, including any additional relevant information - such as production technology, packaging, feedstock and technical parameters. + such as production technology, production technology, packaging, process, feedstock + and technical parameters (e.g. dimensions). Products which are services + (i.e. consulting) should include a short description of the service. type: string productIds: description: > @@ -321,7 +333,7 @@ components: 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 - Given feedback this code is not commonly used, this attribute will become optional in v3 + Advisement: This property will become optional in v3 $ref: '#/components/schemas/NonEmptyString' productClassifications: description: > @@ -342,6 +354,7 @@ components: 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' @@ -354,7 +367,7 @@ components: CarbonFootprint: description: ^ The CarbonFootprint represents the carbon footprint of a product and related data - in accordance with the PACT Framework. + in accordance with the PACT Methodology. title: CarbonFootprint type: object required: @@ -484,6 +497,7 @@ components: 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 comment: This property is deprecated and only kept to ensure backwards-compatibility. It will be removed in version 3. It is replaced by ipccCharacterizationFactors. @@ -500,7 +514,7 @@ components: reporting. This field indicates the IPCC version of the GWP characterization factors used in the calculation of the PCF. - Per the Framework, the latest available characterization factor version shall + Per the PACT Methodology, the latest available characterization factor version shall be used, i.e., [""AR6""]. In the event this is not possible, include the set of all characterization factors used." type: array @@ -577,6 +591,7 @@ components: 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: > @@ -663,14 +678,16 @@ components: 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 + with the PACT Methodology (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: > @@ -696,15 +713,15 @@ components: primaryDataShare: description: > Share of primary data in the final PCF, calculated according to - the Framework. + the PACT Methodology. $ref: '#/components/schemas/Percent' dqi: description: > - Data Quality Indicators (dqi) in accordance with the Framework. + Data Quality Indicators (dqi) in accordance with the PACT Methodology. $ref: '#/components/schemas/DataQualityIndicators' assurance: description: > - If present, the Assurance information in accordance with Framework. + If present, the Assurance information in accordance with PACT Methodology. $ref: '#/components/schemas/Assurance' PositiveNonZeroDecimal: type: string @@ -794,35 +811,35 @@ components: technologicalDQR: description: > Quantitative data quality rating (DQR) based on the data quality matrix - (Framework Table 9), scoring the technological representativeness of the + (PACT Methodology 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 + (PACT Methodology 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 + (PACT Methodology 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 + (PACT Methodology 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 + (PACT Methodology 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' @@ -841,7 +858,7 @@ components: properties: assurance: description: > - True or False to indicate whether the PCF has been assured in line with the Framework. + True or False to indicate whether the PCF has been assured in line with the PACT Methodology. type: boolean coverage: description: > @@ -869,6 +886,7 @@ components: 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: >