index.bs

<pre class='metadata'>
Text Macro: DATE 20230201
Text Macro: VERSION 1.0.1
Text Macro: STATUS Release
Title: Technical Specifications for PCF Data Exchange
Complain About: mixed-indents no
Level: 1
Status: LD
Shortname: data-exchange-protocol
TR: https://wbcsd.github.io/tr/2023/data-exchange-protocol-20230201/
Mailing List: pact@wbcsd.org
Editor:
  Martin Pompéry, SINE Foundation https://sine.foundation/, martin@sine.foundation
  Cecilia Valeri, WBCSD https://www.wbcsd.org/, valeri@wbcsd.org
Abstract: This document specifies a data model for GHG emission data at product level based on the Pathfinder Framework Version 1, and a protocol for interoperable exchange of GHG emission data at product level.
Repository: wbcsd/data-exchange-protocol
Markup Shorthands: markdown yes, idl yes, dfn yes
Boilerplate: omit copyright, omit conformance
Local Boilerplate: header yes
Metadata Include: This version off
</pre>

# Introduction # {#intro}

This document is the first specification in the context of the [=Pathfinder Network=]. It contains technical specifications to enable the exchange of standardized greenhouse gas ([=GHG=]) data at product level across [=interoperable=] [=host system|technology solutions=] (i.e., the Use Case 001).

This Use Case 001 document specifies a [[#data-model|data model]] and an [[#api|HTTP REST API]] for the interoperable exchange of product footprint information with a special focus on [=PCF|product carbon footprints=] ([=PCF=]) between independent solutions. It further specifies rules for conformance of [=host systems=], the [[#data-model|digital representation of product footprints]] and related data data life cycle rules.

The semantic foundation of the data model is the [=Pathfinder Framework|Pathfinder Framework Version 1=].

Developer resources can be found at the [Use Case 001 repository](https://github.com/wbcsd/cti-usecase-001).

Note: Version 2 of this specification can be accessed [here](v2/).

## Scope ## {#scope}

The scope of this document and the feature coverage of the HTTP REST API is intentionally minimal by design. This document will be revised and additional use cases specified at a later stage, building on these specifications. The scope may be extended in future versions, for example to include services.


## Intended Audience ## {#audience}

This document is for

- software developers who want to build software for the exchange of product footprints according to the Pathfinder Framework;
- auditors and sustainability experts who want to understand the data semantics of product footprints or how they are exchanged between partners; and
- anyone that wants to understand more about the technological foundations of the Pathfinder Network.

All parties are encouraged to review the technical specifications, inform the Partnership for Carbon Transparency (PACT), and [SINE Foundation](https://sine.foundation/) of any feedback ([pact@wbcsd.org](mailto:pact@wbcsd.org)), and implement their own interoperable solutions.


## About PACT and the Pathfinder Network ## {#about-pact}

The Pathfinder Network is a concept developed by PACT and powered by the World Business Council for Sustainable Development (WBCSD). PACT is working toward the vision of an open and global network of interoperable solutions for the secure peer-to-peer exchange of accurate, primary and verified product emissions data – across all industries and value chains.

For further information, please refer to the PACT website [www.carbon-transparency.com](www.carbon-transparency.com) and the [Pathfinder vision paper](https://www.carbon-transparency.com/media/luhii1or/pathfinder-network-vision-paper.pdf).


## Disclaimer ## {#disclaimer}

This document is published as a version 1, acknowledging that additions or adjustments may be necessary (e.g., following an update of the Pathfinder Framework later this year). We will do our best to ensure updates do not create compatibility concerns, though we cannot exclude this possibility completely. While PACT encourages the implementation of the technical specifications by all entities to start creating a harmonized system, neither PACT, WBCSD, nor any other individuals who contributed to the development of this document assume responsibility for any consequences or damages resulting directly or indirectly from the use of this document.


## Changelog ## {#changelog}

### Version 1.0.1 ### {#changelog-1.0.1}

The following changes have been applied for version 1.0.1

1. Addition of data type {{RegionOrSubregion}}, cleaning up the definition of property <{CarbonFootprint/geographyRegionOrSubregion}>
2. Fix to the JSON representation specification in [[#dt-crosssectoralstandardset-json]]
3. Change to the minimum size of the set [[#dt-productorsectorspecificruleset]] from `0` to `1`, aligning with the overall specification.
4. Removal of unreferenced data type `Boolean` from the data model section
5. Rewording, simplified wording of chapter [[#api-action-auth]]
6. Addition of an authentication flow specification in chapter [[#api-auth]]
7. Improved wording of request parameter `Filter` in section [[#api-action-list-request]]
8. Improved wording in section [[#api-error-responses]], specifically
    - addition of [=error response=] definition
    - improved specification of the [=error response=] JSON representation
    - consolidated specification of overall [=error response=] representation as a HTTP Response
    - improvements to previous subsection "List of error codes", plus merging into overall section [[#api-error-responses]]
    - addition of list of example situations when an [=error response=] is returned
9. Addition of Section [[#api-error-response-example]]
10. Addition of term [=interoperable=] to section [[#terminology]], plus linking to in respective sections
11. Addition of Terms [=UN geographic region=] and [=UN geographic subregion=]
12. Introduction of a new property table layout in section [[#dt-carbonfootprint]] and [[#dt-pf]]
13. Removal of data types `PositiveDecimal`, `SpecVersionString`, `VersionInteger`

## Acknowledgements ## {#acknowledgements}

WBCSD would like to thank all PACT members, WBCSD staff, and others who shared their detailed and thoughtful input and contributed actively to the development of this document.
WBCSD would also like to express special thanks to the companies participating in the pilot for testing the [=interoperable=] exchange of GHG emissions data across different solutions, as well as to those [=Solution Providers=] who have contributed to this document.


## License ## {#section-license}

The license can be found in [[#license]].


# Terminology # {#terminology}

: <dfn>Data recipient</dfn>
:: The [=SCA|Supply Chain Actor=] requesting and/or receiving [=PCF=] data from another [=SCA=].

: <dfn>Data owner</dfn>
:: The SCA sharing/being asked to share PCF data with another SCA.

: <dfn>interoperable</dfn>
:: The quality of being able to exchange data between [=host systems=] irrespective of the vendors of the host systems, without the need for translation or transformation of the data.

: <dfn>GHG</dfn> (Greenhouse Gas (emissions))
:: Gaseous constituents of the atmosphere, both natural and anthropogenic, that absorb and emit radiation at specific wavelengths within the spectrum of infrared radiation emitted by the Earth’s surface, its atmosphere and clouds. GHGs include CDCO₂, Methane (CH4), Nitrous Oxide(N₂O), Hydrofluoro-Carbons (HFCs), Perfluorocarbons (PFCs) and Sulfur Hexafluoride (SF6).

: Partnership for Carbon Transparency (<dfn>PACT</dfn>)
:: A WBCSD-led group of companies and organizations working together to develop a global and open network for the secure peer-to-peer exchange of accurate, primary and verified product emissions data. See [www.carbon-transparency.com](www.carbon-transparency.com) for more information.

: <dfn>Pathfinder Framework</dfn>
:: Guidance for the Accounting and Exchange of Product Life Cycle Emissions, building on existing standards and protocols, such as the GHG Protocol Product standard). See the [Pathfinder Framework Version 1](https://www.carbon-transparency.com/media/oymlyn4n/pathfinder-framework-version-1_final.pdf) for details.

: <dfn>Pathfinder Network</dfn>
:: An information network of and for supply chain actors to securely exchange environmental data with each other, with an initial focus on PCF data.

: Product Carbon Footprint (<dfn>PCF</dfn>)
:: The carbon (equivalent) emissions relating to a product. Products can be any kind of item exchanged between entities, including “pieces”, metric or volumetric quantities of a product, etc. The <{ProductFootprint}> data model is a digital representation of a PCF in accordance with the [=Pathfinder Framework=].

: Supply Chain Actor (<dfn>SCA</dfn>)
:: An entity intending on exchanging PCF data with another entity using the technical means specified in this document.

: <dfn>Solution Provider</dfn>
:: An entity providing technical solutions to SCAs by implementing and offering [=host systems=].

: <dfn>UN geographic region</dfn>, <dfn>UN geographic subregion</dfn>
:: See [https://unstats.un.org/unsd/methodology/m49/](https://unstats.un.org/unsd/methodology/m49/) for details.




# Conformance # {#conformance}

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY, MUST, MUST NOT, OPTIONAL, RECOMMENDED, REQUIRED, SHOULD, and SHOULD NOT in this document are to be interpreted as described in [[!RFC2119]] [[!RFC8174]] when, and only when, they appear in all capitals, as shown here.

A conforming [=host system=] is any algorithm realized as software and/or hardware that complies with the relevant normative statements in [[#api]].

A conforming requesting [=data recipient=] is any algorithm realized as software and/or hardware that complies with the relevant normative statements in [[#api]].




# Data Model # {#data-model}

<div class=note>Non-normative</div>

This section specifies a data model for [[#dt-pf|product footprints]] conforming with the [=Pathfinder Framework=] guidelines. Additionally, this section specifies the [[#pf-json-schema|data model representation]] in [JavaScript Object Notation (JSON)](https://www.ecma-international.org/publications-and-standards/standards/ecma-404/).


## Data Type: <dfn element>ProductFootprint</dfn> ## {#dt-pf}

Issue: This section needs to motivate the structure of a ProductFootprint and explain its nature as a data container for impact-related data

A `ProductFootprint` represents the carbon footprint of a product with values in accordance with the Pathfinder Framework.

<div class=note>
  Each ProductFootprint relates to a specific product, identified by 1 or more product identifiers. The data type ProductFootprint is modeled as a multi purpose container for product-specific factors.
</div>

### Properties ### {#pf-properties}

A ProductFootprint has the following properties:

<figure id="pf-properties-table" dfn-type="element-attr" dfn-for="ProductFootprint">
	<table class="data">
		<thead>
			<tr>
				<th>Property
				<th>Type
				<th>Req
        <th>Specification
		<tbody>
			<tr>
				<td><dfn>id</dfn> : [=PfId=]
				<td>String
				<td>M
        <td>The product footprint identifier, See [[#dt-pfid]] for details.
			<tr>
				<td><dfn>specVersion</dfn>
				<td>String
				<td>M
        <td>
            The version of the ProductFootprint data specification.
            The value of `specVersion` MUST be `1.0.0`.

			<tr>
				<td><dfn>version</dfn>
				<td>Number
				<td>M
        <td>The version of the <{ProductFootprint}> with value an integer in the inclusive range of `0..2^31-1`.

			<tr>
				<td><dfn>created</dfn> : [=DateTime=]
				<td>String
				<td>M
        <td>A ProductFootprint MUST include the property `created` with value the timestamp of the creation of the ProductFootprint.

			<tr>
				<td><dfn>updated</dfn> : [=DateTime=]
				<td>String
				<td>O
        <td>A ProductFootprint SHOULD include the property `updated` with value the timestamp of the ProductFootprint update. A ProductFootprint MUST NOT include this property if an update has never been performed. The timestamp MUST be in UTC.

			<tr>
				<td><dfn>companyName</dfn>
				<td>String
				<td>M
        <td>The name of the company that is the ProductFootprint Data Owner, with value a non-empty [=String=].
			<tr>
				<td><dfn>companyIds</dfn> : [=CompanyIdSet=]
				<td>Array
				<td>M
        <td>The non-empty set of Uniform Resource Names ([[!RFC8141|URN]]). Each value of this set is supposed to uniquely identify the ProductFootprint Data Owner. See [=CompanyIdSet=] for details.
			<tr>
				<td><dfn>productDescription</dfn> (mandatory, data type: [=String=])
				<td>String
				<td>M
        <td>The free-form description of the product plus other information related to it such as production technology or packaging.
			<tr>
				<td><dfn>productIds</dfn> : [=ProductIdSet=]
				<td>Array
				<td>M
        <td>The non-empty set of [=ProductIds=]. Each of the values in the set is supposed to uniquely identify the product. What constitutes a suitable product identifier depends on the product, the conventions, contracts, and agreements between the [=Data Owner=] and a [=Data Recipient=] and is out of the scope of this specification.
			<tr>
				<td><dfn>productCategoryCpc</dfn> : [=CpcCode=]
				<td>String
				<td>M
        <td>A UN Product Classification Code (CPC) that the given product belongs to.
			<tr>
				<td><dfn>productNameCompany</dfn>
				<td>String
				<td>M
        <td>The non-empty trade name of the product.
			<tr>
				<td><dfn>comment</dfn>
				<td>String
				<td>M
        <td>
          The additional information related to the product footprint.

          Whereas the property <{ProductFootprint/productDescription}> contains product-level information, <{ProductFootprint/comment}> SHOULD be used for information and instructions related to the calculation of the footprint, or other information which informs the ability to interpret, to audit or to verify the Product Footprint.
			<tr>
				<td><dfn>pcf</dfn> : <{CarbonFootprint}>
				<td>Object
				<td>M
        <td>The carbon footprint of the given product with value conforming to the data type <{CarbonFootprint}>.
	</table>
	<figcaption>Properties of data type ProductFootprint</figcaption>

</figure>

Advisement: Subsequent revisions of this data model specification will update the value of <{ProductFootprint/specVersion}> according to the rules of [Semantic Versioning 2.0.0](https://semver.org/lang/de/).



## Data Type: <dfn element>CarbonFootprint</dfn> ## {#dt-carbonfootprint}

A CarbonFootprint represents the carbon footprint of a product and related data in accordance with the Pathfinder Framework.

### Scope of a CarbonFootprint ### {#dt-carbonfootprint-scope}

Each CarbonFootprint is scoped by
1. Time: the time is defined by property <{CarbonFootprint/reportingPeriodStart}> (including) and property <{CarbonFootprint/reportingPeriodEnd}> (excluding); see the [=Pathfinder Framework=] Section 7.2.1
2. Geography: further set by the properties <{CarbonFootprint/geographyRegionOrSubregion}>, <{CarbonFootprint/geographyCountry}>, and <{CarbonFootprint/geographyCountrySubdivision}>; see the [=Pathfinder Framework=] Section 7.2.2.

If a CarbonFootprint
1. Has geographical granularity `Global`, then the properties <{CarbonFootprint/geographyCountry}> and <{CarbonFootprint/geographyRegionOrSubregion}> and <{CarbonFootprint/geographyCountrySubdivision}> MUST be `undefined`;
2. Has a regional or sub-regional geographical granularity, then the property <{CarbonFootprint/geographyRegionOrSubregion}> MUST be `defined` and the properties <{CarbonFootprint/geographyCountry}> and <{CarbonFootprint/geographyCountrySubdivision}> MUST be `undefined`;
3. Has a country-specific geographical granularity, then property <{CarbonFootprint/geographyCountry}> MUST be `defined` AND the properties <{CarbonFootprint/geographyRegionOrSubregion}> and <{CarbonFootprint/geographyCountrySubdivision}> MUST be `undefined`;
4. Has a country subdivision-specific geographical granularity, then property <{CarbonFootprint/geographyCountrySubdivision}> MUST be `defined` AND the properties <{CarbonFootprint/geographyRegionOrSubregion}> and <{CarbonFootprint/geographyCountry}> MUST be `undefined`.


An overview of the relationship between the geographic scope and the definedness or undefinedness of properties is given in the following table:

<figure id="pdf-geographic-scopes-table">
	<table class="data">
		<thead>
			<tr>
				<th>Geographical Granularity / Level of aggregation
				<th>Property `geographyRegionOrSubregion`
				<th>Property `geographyCountry`
        <th>Property geographyCountrySubdivision
		<tbody>
			<tr>
				<td>Global
				<td>`undefined`
				<td>`undefined`
        <td>`undefined`
			<tr>
				<td>Regional or Subregional
				<td>`defined`
				<td>`undefined`
				<td>`undefined`
			<tr>
				<td>Country
				<td>`undefined`
				<td>`defined`
				<td>`undefined`
			<tr>
				<td>Subdivision
				<td>`undefined`
				<td>`undefined`
				<td>`defined`
	</table>
	<figcaption>Geographic scope and definedness of CarbonFootprint properties</figcaption>

</figure>


### Properties ### {#dt-carbonfootprint-properties}

The properties of a CarbonFootprint:

<figure id="pf-carbonfootprint-properties-table" dfn-type="element-attr" dfn-for="CarbonFootprint">
	<table class="data">
		<thead>
			<tr>
				<th>Property
				<th>Type
				<th>Req
        <th>Specification
		<tbody>
			<tr>
				<td><dfn>declaredUnit</dfn> : {{DeclaredUnit}}
				<td>String
				<td>M
        <td>The unit of analysis of the product. See Data Type {{DeclaredUnit}} for further information.
			<tr>
				<td><dfn>unitaryProductAmount</dfn> : [=Decimal=]
				<td>String
				<td>M
        <td>The amount of <{CarbonFootprint/declaredUnit|Declared Units}> contained within the product to which the [[#dt-carbonfootprint|PCF]] is referring to. The value MUST be strictly greater than `0`.
			<tr>
				<td><dfn>fossilGhgEmissions</dfn> : [=Decimal=]
				<td>String
				<td>M
        		<td>
					The emissions from the combustion of fossil sources. The value MUST be calculated per <{CarbonFootprint/declaredUnit|declared unit}> with unit `kg of CO2 equivalent per kilogram` (`kgCO2e / kg`).
            		The value MUST be a [=decimal=] equal to or greater than zero.
			<tr>
				<td><dfn>biogenicEmissions</dfn> : <{BiogenicEmissions}>
				<td>Object
				<td>O
        <td>If present, the value MUST be the biogenic emission factors conforming to data type <{BiogenicEmissions}>.
			<tr>
				<td><dfn>biogenicCarbonContent</dfn> : [=Decimal=]
				<td>String
				<td>M
        		<td>The mass of biogenic carbon per given <{CarbonFootprint/unitaryProductAmount|unit of exchange}>  (see the [=Pathfinder Framework=]), expressed as a decimal equal to or greater than zero with unit `kg CO2eq per declared unit`.
			<tr>
				<td><dfn>reportingPeriodStart</dfn> (mandatory, data type: [=DateTime=])
				<td>String
				<td>M
        <td>The start of the reporting period. See the [=Pathfinder Framework=] Section 7.2.1. For further information on time representation, see the definition of data type [=DateTime=].
			<tr>
				<td><dfn>reportingPeriodEnd</dfn> : [=DateTime=]
				<td>String
				<td>M
        <td>The end (excluding) of the reporting period. See the Pathfinder Framework Section 7.2.1.
			<tr>
				<td><dfn>geographyCountrySubdivision</dfn>
				<td>String
				<td>
        <td>If present, a ISO 3166-2 Subdivision Code. See [[#dt-carbonfootprint-scope]] for further details.

              Example value for the State of New York in the United States of America:
              <div class=example>`US-NY`</div>
              Example value for the department Yonne in France
              <div class=example>`FR-89`</div>
			<tr>
				<td><dfn>geographyCountry</dfn> : [=ISO3166CC=]
				<td>String
				<td>
        <td>If present, the value MUST conform to data type [=ISO3166CC=]. See [[#dt-carbonfootprint-scope]] for further details.
              Example value in case the geographic scope is France
              <div class=example>`FR`</div>
			<tr>
				<td><dfn>geographyRegionOrSubregion</dfn> : {{RegionOrSubregion}}
				<td>String
				<td>
        <td>If present, the value MUST conform to data type {{RegionOrSubregion}}. See [[#dt-carbonfootprint-scope]] for further details.     Additionally, see the [=Pathfinder Framework=] Section 7.2.2.

              Advisement: The set of region identifiers will likely change in future revisions. It is recommended to account for this when implementing the validation of this property.
			<tr>
				<td><dfn>primaryDataShare</dfn> : [=Percent=]
				<td>Number
				<td>M
        <td>The share of primary data in percent. See the Pathfinder Framework Section 7.2.3.
			<tr>
				<td> <dfn>emissionFactorSources</dfn> : <{EmissionFactorDSSet}>
				<td>Array
				<td>O
        <td>
            If secondary data was used to calculate the <{CarbonFootprint}>, then it MUST include the property <{CarbonFootprint/emissionFactorSources}> with value the emission factors used for the <{CarbonFootprint}> calculation.

            See the Pathfinder Framework Section 6.2.

            If no secondary data is used, this property MUST BE `undefined`.
			<tr>
				<td> <dfn>boundaryProcessesDescription</dfn>
				<td>String
				<td>O
        <td>
            If present, the processes attributable to each lifecycle stage. If no such description is available or otherwise provided, then this property MUST NOT be included.

            Example text value:
            <div class=example>`Electricity consumption included as an input in the production phase`</div>
			<tr>
				<td><dfn>crossSectoralStandardsUsed</dfn> : [=CrossSectoralStandardSet=]
				<td>Array
				<td>M
        <td>The cross-sectoral standards applied for calculating or allocating [=GHG=] emissions
			<tr>
				<td><dfn>productOrSectorSpecificRules</dfn> : [=ProductOrSectorSpecificRuleSet=]
				<td>Array
				<td>M
        <td>The product-specific or sector-specific rules applied for calculating or allocating GHG emissions. If no product or sector specific rules were followed, this set MUST be empty.
			<tr>
				<td><dfn>allocationRulesDescription</dfn>
				<td>String
				<td>O
        <td>If present, the description of the allocation rules applied.

	</table>
	<figcaption>Properties of data type CarbonFootprint</figcaption>

</figure>

Note: The property <{CarbonFootprint/biogenicEmissions}> will be revised once the GHG Protocol FLAG Standard is published.

Issue: Property <{CarbonFootprint/unitaryProductAmount}> needs better specification text


## Data Type: <dfn enum>RegionOrSubregion</dfn> ## {#dt-regionorsubregion}

The data type `RegionOrSubregion` MUST be encoded as a [=String=] with value equal to one of the following values:

<dl dfn-type="enum-value" dfn-for="RegionOrSubregion">

: <dfn>Africa</dfn>
:: for the [=UN geographic region=] Africa

: <dfn>Americas</dfn>
:: for the [=UN geographic region=] Americas

: <dfn>Asia</dfn>
:: for the [=UN geographic region=] Asia

: <dfn>Europe</dfn>
:: for the [=UN geographic region=] Europe

: <dfn>Oceania</dfn>
:: for the [=UN geographic region=] Oceania

: <dfn>Australia and New Zealand</dfn>
:: for the [=UN geographic subregion=] Australia and New Zealand

: <dfn>Central Asia</dfn>
::  for the [=UN geographic subregion=] Central Asia

: <dfn>Eastern Asia</dfn>
:: for the [=UN geographic subregion=] Eastern Asia

: <dfn>Eastern Europe</dfn>
:: for the [=UN geographic subregion=] Eastern Europe

: <dfn>Latin America and the Caribbean</dfn>
:: for the [=UN geographic subregion=] Latin America and the Caribbean

: <dfn>Melanesia</dfn>
:: for the [=UN geographic subregion=] Melanesia

: <dfn>Micronesia</dfn>
:: for the [=UN geographic subregion=] Micronesia

: <dfn>Northern Africa</dfn>
:: for the [=UN geographic subregion=] Northern Africa

: <dfn>Northern America</dfn>
:: for the [=UN geographic subregion=] Northern America

: <dfn>Northern Europe</dfn>
::  for the [=UN geographic subregion=] Northern Europe

: <dfn>Polynesia</dfn>
:: for the [=UN geographic subregion=] Polynesia

: <dfn>South-eastern Asia</dfn>
:: for the [=UN geographic subregion=] South-eastern Asia

: <dfn>Southern Asia</dfn>
:: for the [=UN geographic subregion=] Southern Asia

: <dfn>Southern Europe</dfn>
:: for the [=UN geographic subregion=] Southern Europe

: <dfn>Sub-Saharan Africa</dfn>
:: for the [=UN geographic subregion=] Sub-Saharan Africa

: <dfn>Western Asia</dfn>
:: for the [=UN geographic subregion=] Western Asia

: <dfn>Western Europe</dfn>
:: for the [=UN geographic subregion=] Western Europe

</dl>


## Data Type: <dfn element>EmissionFactorDSSet</dfn> ## {#dt-emissionfactordataset}

A set of <{EmissionFactorDS|Emission Factor Data Sources}> of size 1 or larger.

### JSON Data Representation ### {#dt-emissionfactordataset-json}

As an array of objects, with each object conforming to the JSON representation of <{EmissionFactorDS}>.


## Data Type: <dfn element>EmissionFactorDS</dfn> ## {#dt-emissionfactords}

An EmissionFactorDS references emission factor databases accepted under Version 1 of the Pathfinder Framework Section 6.2.

Note: Version 2 of the Pathfinder Framework will extend the coverage of emission factors data sources. This specification will reflect upcoming changes in future versions.

### Properties ### {#dt-emissionfactords-properties}

<dl dfn-type="element-attr" dfn-for="EmissionFactorDS">

: <dfn>name</dfn> (mandatory, data type: [=NonEmptyString=])
:: Each EmissionFactorDS MUST include the property `name` with value the name of the emission factor database.

: <dfn>version</dfn> (mandatory, data type: [=NonEmptyString=])
:: Each EmissionFactorDS MUST include the property `version` with value the version of the emission factor database used.

</dl>

### JSON Representation ### {#dt-emissionfactords-json}

Each <{EmissionFactorDS}> MUST be encoded as a JSON object.



## Data Type: <dfn element>BiogenicEmissions</dfn> ## {#dt-biogenicemissions}

BiogenicEmissions contains biogenic emission values according to the GHG Protocol FLAG Standard.

### Properties ### {#dt-biogenicemissions-properties}

Data type <{BiogenicEmissions}> has the following properties.

At least one property of a <{BiogenicEmissions}> MUST be present.

<figure id="pf-biogenicemissions-properties-table" dfn-type="element-attr" dfn-for="ProductFootprint">
	<table class="data">
		<thead>
			<tr>
				<th>Property
        <th>Specification
		<tbody>
			<tr>
				<td><dfn>landUseEmissions</dfn> : [=Decimal=]
        <td>If present, the land use emissions (e.g. cultural practice) as a decimal number equal to, greater or lower than zero.

			<tr>
				<td><dfn>landUseChangeEmissions</dfn>: [=Decimal=]
        <td>If present, the land use change emissions (e.g. due to deforestation) as a decimal number equal to, greater or lower than zero. This value must include direct land use change (dLUC) where available, otherwise statistical land use change (sLUC) can be used. If available, including indirect land use change (iLUC) to remain optional.

			<tr>
				<td><dfn>otherEmissions</dfn> : [=Decimal=]
        <td>If present, the other emissions (e.g. biogenic waste treatment) as a decimal number equal to, greater or lower than zero.
  </table>
	<figcaption>Properties of data type BiogenicEmissions</figcaption>
</figure>



## Data Type: <dfn enum>CrossSectoralStandard</dfn> ## {#dt-crosssectoralstandard}

CrossSectoralStandard is the enumeration of accounting standards used for product carbon footprint calculation. Valid values are

<dl dfn-type="enum-value" dfn-for="CrossSectoralStandard">

: <dfn>GHG Protocol Product standard</dfn>
:: for the GHG Protocol Product standard

: <dfn>ISO Standard 14067</dfn>
:: for ISO Standard 14067

: <dfn>ISO Standard 14044</dfn>
:: for ISO Standard 14044

</dl>

### JSON Reprsentation ### {#dt-crosssectoralstandard-json}

Each CrossSectoralStandard MUST be encoded as a JSON string.



## Data Type: <dfn>CrossSectoralStandardSet</dfn> ## {#dt-crosssectoralstandardset}

A set of {{CrossSectoralStandard}} values.

### JSON Representation ### {#dt-crosssectoralstandardset-json}

As an array of strings, with each string conforming to the JSON representation of {{CrossSectoralStandard}}.


## Data Type: <dfn element>ProductOrSectorSpecificRule</dfn> ## {#dt-productorsectorspecificrule}

A ProductOrSectorSpecificRule refers to a set of product or sector specific rules published by a specific operator and applied during product carbon footprint calculation.

### Properties ### {#dt-productorsectorspecificrule-properties}

<dl dfn-type="element-attr" dfn-for="ProductOrSectorSpecificRule">

: <dfn>operator</dfn> (mandatory, data type: {{ProductOrSectorSpecificRuleOperator}})
:: A ProductOrSectorSpecificRule MUST include the property `operator` with the value conforming to data type {{ProductOrSectorSpecificRuleOperator}}.

: <dfn>ruleNames</dfn> (mandatory, data type: [=NonEmptyStringVector=])
:: A ProductOrSectorSpecificRule MUST include the property `ruleNames` with value the non-empty set of rules applied from the specified <{ProductOrSectorSpecificRule/operator}>.

: <dfn>otherOperatorName</dfn> (optional, data type: [=NonEmptyString=])
::
    If the value of property <{ProductOrSectorSpecificRule/operator}> is `Other`, a <{ProductOrSectorSpecificRule}> MUST include the property `otherOperatorName` with value the name of the operator. In this case, the operator declared MUST NOT be included in the definition of {{ProductOrSectorSpecificRuleOperator}}.
    If the value of property operator is NOT Other, the property <{ProductOrSectorSpecificRule/otherOperatorName}> of a <{ProductOrSectorSpecificRule}> MUST be `undefined`.

</dl>

### JSON Representation ### {#dt-productorsectorspecificrule-json}

Each <{ProductOrSectorSpecificRule}> MUST be encoded as a JSON object.



## Data Type: <dfn>ProductOrSectorSpecificRuleSet</dfn> ## {#dt-productorsectorspecificruleset}

A set of ProductOrSectorSpecificRule of size 1 or larger.

### JSON Representation ### {#dt-productorsectorspecificruleset-json}

Each [=ProductOrSectorSpecificRuleSet=] MUST be encoded as an array of JSON objects, with each object conforming to [[#dt-productorsectorspecificrule-json]].




## Data Type: <dfn enum>ProductOrSectorSpecificRuleOperator</dfn> ## {#dt-productorsectorspecificruleoperator}

A ProductOrSectorSpecificRuleOperator is the enumeration of Product Category Rule (PCR) operators. Valid values are:

<dl dfn-type="enum-value" dfn-for="ProductOrSectorSpecificRuleOperator">

: <dfn>PEF</dfn>
:: for EU / <a href="https://ec.europa.eu/environment/archives/eussd/pdf/footprint/PEF%20methodology%20final%20draft.pdf">PEF</a> Methodology PCRs

: <dfn>EPD International</dfn>
:: for PCRs authored or published by [EPD International](https://www.environdec.com/)

: <dfn>Other</dfn>
:: for a PCR not published by the operators mentioned above

</dl>

### JSON Reprsentation ### {#dt-productorsectorspecificruleoperator-json}

Each value is encoded as a JSON String.



## Data Type: <dfn>NonEmptyStringVector</dfn> ## {#dt-nonemptystringvector}

A list of [=NonEmptyString=] of length 1 or greater.

### JSON Representation ### {#dt-nonemptystringvector-json}

Each NonEmptyStringVector MUST be encoded as an array of [=NonEmptyStrings=].


## Data Type: <dfn>CpcCode</dfn> ## {#dt-cpccode}

A CpCode represents a UN CPC Code version 2.1 value.

Example value of the CPC code for "wood in chips or particles":
<div class="example">`31230`</div>

### JSON Representation ### {#dt-cpccode-json}

Each CpcCode MUST be encoded as a JSON String.


## Data Type: <dfn enum>DeclaredUnit</dfn> ## {#dt-declaredunit}

DeclaredUnit is the enumeration of accepted declared units with values

<dl dfn-type="enum-value" dfn-for="DeclaredUnit">

: <dfn>liter</dfn>
:: for unit liter

: <dfn>kilogram</dfn>
:: for unit kilogram

: <dfn>cubic meter</dfn>
:: for cubic meter

: <dfn>kilowatt hour</dfn>
:: for kilowatt hour

: <dfn>megajoule</dfn>
:: for megajoule

: <dfn>ton kilometer</dfn>
:: for ton kilometer

: <dfn>square meter</dfn>
:: for square meter

</dl>

### JSON Reprsentation ### {#dt-}

The value of each {{DeclaredUnit}} MUST be encoded as a JSON String.


## Data Type: <dfn>NonEmptyString</dfn> ## {#dt-nonemptystring}

A String with 1 or more characters.

### JSON Representation ### {#dt-nonemptystring-json}

Each NonEmptyString MUST be encoded as a JSON String.



## Data Type: <dfn>CompanyIdSet</dfn> ## {#dt-companyidset}

A set of [=URNs=] of length 1 or greater.

### JSON Representation ### {#dt-companyidset-json}

Each [=CompanyIdSet=] MUST be encoded as an array of strings.




## Data Type: <dfn>ProductIdSet</dfn> ## {#dt-productidset}

A set of [=ProductIds=] of size 1 or larger.

### JSON Representation ### {#dt-productidset-json}

Each ProductIdSet MUST be encoded as an array of strings.



## Data Type: <dfn>ProductId</dfn> ## {#dt-productid}

Each ProductId MUST be a conforming [=URN=] with as namespace a value included in the Official IANA Registry of URN Namespaces.



## Data Type: <dfn>URN</dfn> ## {#dt-urn}

A String conforming to the [[!RFC8141|URN syntax]].

### JSON Representation ### {#dt-urn-json}

Each [=URN=] MUST be encoded as a JSON String.


## Data Type: <dfn>String</dfn> ## {#dt-string}

A regular UTF-8 String.

### JSON Data Representation ### {#dt-string-json}

Each [=String=] MUST be encoded as a JSON String.



## Data Type: <dfn>Percent</dfn> ## {#dt-percent}

A Decimal number in the range of and including `0` and `100`.

Example values:
<div class=example>
    - `100`
    - `23.0`
    - `7.183924`
    - `0.0`
</div>

### JSON Representation ### {#dt-percent-json}

Each Percent MUST be encoded in IEEE-754 [double-precision floating-point format](https://en.wikipedia.org/wiki/Double-precision_floating-point_format) as a JSON number.



## Data Type: <dfn element>StrictlyPositiveDecimal</dfn> ## {#dt-strictlypositivedecimal}

A positive, non-zero Decimal.

Example values:
<div class=example>
    - 0.123
    - 1000
    - 42.102340
</div>

### JSON Representation ### {#dt-strictlypositivedecimal-json}

See [[[#dt-decimal-json]]].



## Data Type: <dfn>DateTime</dfn> ## {#dt-datetime}

Each DateTime MUST be a date and time string conforming to ISO 8601. The timezone MUST be UTC.

Example value for beginning of March, the year 2020, UTC:
<div class=example>
  `2020-03-01T00:00:00Z`
</div>


### JSON Representation ### {#dt-datetime-json}

Each [=DateTime=] MUST be encoded as a JSON String.



## Data Type: <dfn>ISO3166CC</dfn> ## {#dt-iso3166cc}

An ISO 3166-2 alpha-2 country code.

Example value for tue alpha-2 country code of the United States:
<div class=example>
  `US`
</div>

### JSON Representation ### {#dt-iso3166cc-json}

Each [=ISO3166CC=] MUST be encoded as a JSON String.


## Data Type: <dfn>Decimal</dfn> ## {#dt-decimal}

A dotted-decimal number.

Example values:
<div class=example>
    - `10`
    - `42.12`
    - `-182.84`
</div>

### JSON Representation ### {#dt-decimal-json}

Each Decimal MUST be encoded as a JSON String.


## Data Type: <dfn>PfId</dfn> ## {#dt-pfid}

A PfId MUST be a UUID v4 as specified in [[!RFC4122]].


### JSON Representation ### {#dt-pfid-json}

Each PfId MUST be encoded as a JSON String.

Example JSON string value:

<div class=example>
```json
"f4b1225a-bd44-4c8e-861d-079e4e1dfd69"
```
</div>


# Product Footprint Lifecycle # {#lifecycle}


## Introduction ## {#lifecycle-intro}

<div class=note>Non-normative</div>


A [[#dt-pf|Product Footprint]] can be updated, for instance to incorporate a change in upstream carbon emission factors or to correct errors.

The purpose of this section is to clarify what constitutes an occasion for an update ([[#lifecycle-update]]) and to specify which kinds of changes ([[#lifecycle-rules]]) to a Product Footprint must be applied in such a case.


## Definition of update ## {#lifecycle-update}

A Product Footprint update SHOULD be limited to correct reported values.
A Product Footprint update SHOULD be done whenever the value of 1 or more properties of the Product Footprint change which could directly or indirectly affect the Product Footprint calculation or interpretation by data recipients of the Product Footprint.

A Product Footprint update MUST NOT occur to change the [[#dt-carbonfootprint-scope|reporting period]]. For this case, a data owner MUST create a Product Footprint with a new <{ProductFootprint/id|Product Footprint identifier}>.

A Product Footprint update MUST NOT change the <{ProductFootprint/id|Product Footprint identifier}>.


## Data life cycle rules ## {#lifecycle-rules}

A Product Footprint CAN be updated by a data owner.

A Product Footprint update MUST include 1 or more changes to a property, excluding changes to properties <{ProductFootprint/version}> and <{ProductFootprint/updated}>. A change to a property includes a transition to or from being `undefined`.

Whenever a [=data owner=] or a [=host system=] updates a Product Footprint according to [[#lifecycle-update]],

1. it MUST set the value of property <{ProductFootprint/version}> to be by strictly greater than the value of the property <{ProductFootprint/version}> of all preceding footprints, and
2. it SHOULD set the value of property <{ProductFootprint/updated}> to the timestamp of the update. The value SHOULD be strictly greater than the value of the property <{ProductFootprint/updated}> of all preceding Product Footprints.


## JSON Schema ## {#pf-json-schema}

Issue: add JSON Schema for <{ProductFootprint}>.



# Use Case 001 HTTP REST API Version 1.0.0 # {#api}

## Introduction ## {#api-intro}

<div class=note>Non-normative</div>

This section defines an [[!rfc9112|HTTP]]-based API for the [=interoperable=] exchange of [[#dt-pf|Product Footprint]] data between [=host systems=].

This version 1.0.1 release is the first publication towards this goal. Intentionally, the scope of the specifications is minimal in order to collect market feedback and to incorporate this in future revisions.

Issue: reword this introduction




## <dfn>Host System</dfn> ## {#api-host-system}

A host system serves the needs of a single or multiple [=data owners=]. Additionally, a host system can also serve the needs of [=data recipients=] if it retrieves data from host systems by calling the Use Case 001 HTTP REST API ([[#api-actions]]).

Interoperable data exchange between a data owner and a data recipient can be achieved by

1. the data owner offering <{ProductFootprint}> data through a host system that implements the [[#api|Use Case 001 HTTP REST API]], and
2. the data recipient making [[#api-auth|authenticated calls]] to retrieve ProductFootprint data; e.g. by calling the [=Action ListFootprints=].


### Out of scope ### {#api-host-system-out-of-scope}

<div class=note>Non-normative</div>

This standard focuses on the necessary definitions to enable interoperable data exchange between data owners and data recipients. This is mediated through a host system which implements the HTTP REST API defined in this document.

Within the [=PACT=] Project, conforming host systems are called solutions.

Solutions add further functionality on top of this standard in order to enable meaningful and interoperable data exchanges.

The following section briefly describes some of the additional functionality which is beyond the scope of this document:

<ol type="a">
  <li>Footprint calculation according to the Pathfinder Framework</li>
  <li>Authentication and access management: the act of deciding and setting which product footprint may be accessed by each data recipient</li>
  <li>Credentials management: the overall functionality to generate access credentials for data recipients, to exchange these credentials with data recipients, to rotate or revoke such credentials, etc.</li>
  <li>Logging: creation and storage of access logs and audit trails related to data exchange, authentication processes, etc.</li>
</ol>


### Establishing data exchange flows between Host Systems ### {#api-data-exchange}

Issue: add section on data exchange between host systems, detailing the information needed for establishing host system-to-host system data exchange, URL examples


### A note on data synchronization between Host Systems ### {#api-host-system-sync}

<div class=note>Non-normative</div>

The data flow specified in this document is directed.

<div class=example>
  In a supplier-vendor relationship, the supplier is the [=data owner=] and the customer the [=data recipient=]. The data owner has the responsibility to run a [=host system=] (also called "solution") and the data recipient may then retrieve the data through the data owner's host system.
</div>

If a data owner has updated a product footprint, it is assumed that the product footprint is made available through the Use Case 001 HTTP REST API as soon as possible.<br/>
Additionally, each product footprint returned from a host system has properties to disclose whether a product footprint was updated. These properties are: <{ProductFootprint/created}>, <{ProductFootprint/updated}>, <{ProductFootprint/version}>.
By comparing the value of these properties for a product footprint, identified by its <{ProductFootprint/id}>, solutions can determine whether a footprint has been updated.

Note: in future versions, the functionality for data exchange between host systems and capabilities to synchronize data will be specified and developed further.


Issue: add link to product lifecycle section

Issue: reword this section


## Authentication and Request Flows ## {#api-auth}

[=Data recipients=] MUST first retrieve an [=access token=] through [=Action Authenticate=].
This is implemented by
1. the [=data recipient=] calling [=Action Authenticate=] of a [=host system=]
2. the host system issuing an access token as specified in [[!rfc6749]] Section 4.4.3 and Section 5.1
3. the [=data recipient=] calling one or more Actions of the host system
    - using the value of `access_token` of the response of the [=Action Authenticate=] call as the value for a [[!rfc6750]] <dfn>Bearer token</dfn>
    - presenting the Bearer token for subsequent call(s) to the host system in accordance with [[!rfc6750]] Section 2.1

[=Access tokens=] SHOULD expire. In this case, data recipients MUST retrieve a new [=access token=] as described in this section.


## Actions reference ## {#api-actions}

A [=host system=] MUST implement each of the following actions. A host system MUST only accept requests using https, not
http. The host system MUST not respond to requests made using other protocols (not even with a 400 Error or any other http
status codes).

A host system MAY offer the endpoints under a relative subpath. A host system MUST offer the [=Action ListFootprints=] and [=Action GetFootprint=] under the same Hostname and Subpath.


<div class=example>
  The host system's DNS domain name is `example.org` and the subpath is `/wbcsd` whereas the ID management system uses a `id.example.org` domain with an empty subpath. The URIs would then be:

    - for [=Action Authenticate=]: [https://id.example.org/auth/token](https://id.example.org/auth/token)
    - for [=Action ListFootprints=]: [https://example.org/wbcsd/0/footprints](https://example.org/wbcsd/0/footprints)
    - etc.

</div>


### <dfn>Action Authenticate</dfn> ### {#api-action-auth}

Request an access token using client credentials.

Host systems MUST implement this action in conformance with [[!rfc6749]] Section 4.4 (OAuth2 Client Credentials).

Host systems MAY offer this action under a dedicated [=AuthHostname=] and [=AuthSubpath=].

An <dfn>access token</dfn> is the value of `access_token` from a 200 (OK) entity-body derived from a successful call to this action. See [[!rfc6749]] Section 4.4.3 and Section 5.1 for further details.


#### Request Syntax (HTTP/1.1) #### {#api-action-auth-request}

<pre highlight=http>
POST <l>[=AuthSubpath=]</l>/auth/token HTTP/1.1
host: <l>[=AuthHostname=]</l>
accept: application/json
content-type: application/x-www-form-urlencoded
authorization: Basic <l>[=BasicAuth=]</l>
content-length: <l>[=ContentLength=]</l>
content-type: application/x-www-form-urlencoded

<l>[=AuthBody=]</l>
</pre>

With Request parameters:

: <dfn>AuthSubpath</dfn>:
:: If a [=host system=] uses a relative subpath dedicated to the purpose of creating an [=access token=], then the requesting [=data recipient=] MUST prepend this subpath.

: <dfn>AuthHostname</dfn>
:: The requesting data recipient MUST use the domain name of the host system dedicated for the purpose of creating an authentication token.

: <dfn>BasicAuth</dfn>
:: See [[!rfc6749]] Section 4.4.2

: <dfn>AuthBody</dfn>
:: See [[!rfc6749]] Section 4.4

: <dfn>ContentLength</dfn>
:: The length of the Body. See [[!rfc9112]].

#### Response Syntax #### {#api-action-auth-response}

<pre highlight=http>
HTTP/1.1 <l>[=AuthStatusCode=]</l> OK
content-type: application/json
content-length: <l>[=ContentLength=]</l>

<l>[=AuthResponseBody=]</l>
</pre>

With action-specific response parameters

: <dfn>AuthStatusCode</dfn>
:: A HTTP response code conforming to [[!rfc6749]] Section 4.4 and Section 5.

: <dfn>AuthResponseBody</dfn>
:: A JSON Object conforming to RFC 6749 Section 4.4. See [[#api-auth]] for further details


### <dfn>Action ListFootprints</dfn> ### {#api-action-list}

Lists [[#dt-pf|product footprints]] with optional filtering by properties <{ProductFootprint/created}> or <{ProductFootprint/updated}>.

[=Host systems=] SHOULD implement an access management system and only return the [[#dt-pf|product footprints]] for which the [=data owner=] granted access to the requesting [=data recipient=].

#### Request Syntax (HTTP/1.1) #### {#api-action-list-request}

<pre highlight=http>
GET <l>[=Subpath=]</l>/0/footprints?<l>[=Filter=]</l> HTTP/1.1
host: <l>[=Hostname=]</l>
authorization: Bearer <l>[=BearerToken=]</l>
</pre>

with request parameters:

: <dfn>Subpath</dfn>
:: If a host system uses a relative subpath, then the requesting data recipient MUST prepend this subpath.

: <dfn>Hostname</dfn>
:: The requesting data recipient MUST use the domain name of the host system.

: <dfn>BearerToken</dfn>
:: see [=Bearer Token=] of section [[#api-auth]]

: <dfn>Filter</dfn>
::
    `filter` is an optional request parameter. If defined,
        - the name of the HTTP request parameter MUST be `filter`
        - the value of the HTTP request parameter MUST conform to the `$filter` syntax as defined by the [ODatav4 specification](https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html).

        Additionally, the `$filter` statement MUST reference property <{ProductFootprint/created}> or property <{ProductFootprint/updated}> only and MUST use the `eq` operator only.

#### Response Syntax #### {#api-action-list-response}

<pre highlight=http>
HTTP/1.1 <l>[=ListStatusCode=]</l> <l>[=ListStatusText=]</l>
content-type: application/json
content-length: <l>[=ContentLength=]</l>

<l>[=ListResponseBody=]</l>
</pre>


With response parameters

: <dfn>ListStatusCode</dfn>
::
    If the host system returns a list of product footprints, the `HttpStatusCode` MUST be 200.

    If the host system responds with an [=error response=], the `HttpStatusCode` MUST match the HTTP Status Code of the respective [=error response code=].

    If the host system does not return the list of [[#dt-pf|ProductFootprints]], it MUST return an error HTTP Status Code (4xx, 5xx).

: <dfn>ListStatusText</dfn>
::
    The HTTP Status text conforming to the HTTP status code [=ListStatusCode=].

: <dfn>ListResponseBody</dfn>
::
    If the host system accepts the [=access token=], the body MUST be a JSON object with property `data` with value the list of <{ProductFootprint|ProductFootprints}>.
    The list MUST be encoded as a JSON array. If the list is empty, the host system MUST return an empty JSON array.

    Additionally,

      - if the request parameter Filter is defined against property updated, then only ProductFootprints with property updated defined and with a value equal to or greater than the timestamp given by the filter SHOULD be included in the Body; or
      - if the filter is against property created, then only ProductFootprints with a creation time equal to or greater than the timestamp given by the filter SHOULD be included in the Body.

        <div class=example>
          Example value of Filter:

          ```$filter=updated ge 2020-03-01T00:00:00Z```
        </div>

    If the host system does not accept the access token, the body MUST be an error response with code [=AccessDenied=].

    If the host system does not accept the access token because it expired, the body SHOULD be an error response with code [=TokenExpired=].

    In all other cases, for instance in case of a malformed value of the header authorization, the body SHOULD be an error response with code [=BadRequest=].




### <dfn>Action GetFootprint</dfn> ### {#api-action-get}

Retrieves [[#dt-pf|product footprints]].

[=Host systems=] SHOULD implement an access management system and only return the product footprints for which the [=data owner=] granted access to the requesting [=data recipient=].


#### Request Syntax #### {#api-action-get-request}

<pre highlight=http>
GET <l>[=Subpath=]</l>/0/footprints/<l>[=GetPfId=]</l> HTTP/1.1
Host: <l>[=Hostname=]</l>
authorization: Bearer <l>[=BearerToken=]</l>
</pre>

with request-specific parameters:

: <dfn>GetPfId</dfn>
:: The value of property <{ProductFootprint/id}> of a product footprint a [=data recipient=] intends to retrieve.


#### Response Syntax #### {#api-action-get-response}

<pre highlight=http>
HTTP/1.1 <l>[=GetStatusCode=]</l> <l>[=GetStatusText=]</l>
content-type: application/json
content-length: <l>[=ContentLength=]</l>

<l>[=GetResponseBody=]</l>
</pre>

With response parameters:

: <dfn>GetStatusCode</dfn>
::
    The HTTP Status Code of the response.

    If the host system accepts the [=access token=], the HTTP Status Code MUST be 200.<br/>
    If the host system responds with an [=error response=], the HTTP status code MUST match the HTTP Status Code of the respective [=error response code=].<br/>
    If the host system does NOT return a product footprint, the host system MUST return an error HTTP Status Code (4xx, 5xx).

: <dfn>GetStatusText</dfn>
::
    The HTTP Status text conforming to the HTTP status code [=GetStatusCode=].

: <dfn>GetResponseBody</dfn>
::
    If the host system accepts the access token and allows the requesting data recipient to access the requested product footprint, the body MUST be a JSON object with property data. The value of property data MUST be the product footprint with footprint identifier [=GetPfId=].

    If there were changes to the requested product footprint with identifier [=GetPfId=], the host system SHOULD return the latest product footprint identified with identifier [=GetPfId=] and the maximum value of property version.

    Note: If a host system implements the life cycle rules, then the “latest” version of the requested product footprint is the one with the maximum value of version with <{ProductFootprint/id}> equal to [=GetPfId=].

    If the host system does not accept the access token, GetResponseBody MUST be an [=error response=] with code [=AccessDenied=].

    If the host system does not accept the access token because it expired, GetResponseBody SHOULD be an error response with code [=TokenExpired=].

    The host system MAY return an error response with code [=NoSuchFootprint=].

    In all other cases, for instance in case of a malformed value of the header authorization, GetResponseBody SHOULD be an error response with code [=BadRequest=].



## Error responses ## {#api-error-responses}

<div class=example>
 Situations when a [=host system=] returns an error response:
  <ol type="i">
    <li>a [=data recipient=] makes an unauthenticated request (see [[#api-auth]])</li>
    <li>a [=data recipient=] makes a request with an expired access token (see [[#api-auth]])</li>
    <li>a [=data recipient=] makes a request with an invalid access token (see [[#api-auth]])</li>
    <li>a [=data recipient=] makes a request with an invalid request syntax or an invalid request parameter (see [[#api-action-list-request]] and [[#api-action-get-request]])</li>
    <li>a [=host system=] runs into an error while processing the request, returning an [=InternalError=] error response</li>
  </ol>
</div>

Whenever a [=host system=] returns an [=error response=], it MUST send a HTTP response such that
  - the HTTP Status Code equals the `HTTP Status Code` defined for the respective [=error response code=] (see <a href="#api-errors-table">Error Codes Table</a>)
  - with content type set to `application/json`, and
  - with response body the [=error response=]

A <dfn>error response</dfn> is a JSON object with the following properties:
    - `code`: a [=error response code=] encoded as a String
    - `message`: a [=error message=] encoded as a String

A <dfn>error response code</dfn> is a value from column `Error Response Code` from the table below.

A <dfn>error message</dfn> is a human-readable error description. Example values are in column `Example Message` in the table below.

<div class=example>
Example [=AccessDenied=] [=error response=]:

<pre class=include-code>
path: examples/error-response-access-denied.json
highlight: json
</pre>
</div>

A [=host system=] MAY return [=error messages=] different from the table below, for instance localized values depending on a [=data recipient=].

A [=host system=] SHOULD conform to [[!rfc6750]] Section 3 when returning a [=TokenExpired=] [=error response=].


<figure id="api-errors-table">
	<table class="data">
		<thead>
			<tr>
				<th>`Error Response Code`
				<th>`Example Message`
				<th>`HTTP Status Code`
		<tbody>
			<tr>
				<td><dfn>AccessDenied</dfn>
				<td>Access denied
				<td>403
			<tr>
				<td><dfn>BadRequest</dfn>
				<td>Bad Request
				<td>400
			<tr>
				<td><dfn>NoSuchFootprint</dfn>
				<td>The specified footprint does not exist.
				<td>404
			<tr>
				<td><dfn export>NotImplemented</dfn>
				<td>The specified Action or header you provided implies functionality that is not implemented
				<td>400
			<tr>
				<td><dfn>TokenExpired</dfn>
				<td>The specified access token has expired
				<td>401
			<tr>
				<td><dfn>InternalError</dfn>
				<td>An internal or unexpected error has occurred
				<td>500

	</table>
	<figcaption>Listing of error codes and their related error response codes.</figcaption>
</figure>


### Error processing by a data recipient ### {#api-error-responses-processing}

A requesting [=data recipient=] MUST use the code property and potentially also the HTTP Status Code to differentiate between the different errors.



## Examples ## {#api-examples}

<div class=note>Non-normative</div>

### Example Action ListFootprints request and response ### {#api-action-list-example}


<div class="example">

Example request:

<pre highlight=http>
GET /0/footprints HTTP/2
host: api.pathfinder.sine.dev
authorization: Bearer [BearerToken]
</pre>

Example response HTTP headers:
<pre highlight=http>
HTTP/1.1 200 OK
date: Mon, 23 May 2022 19:33:16 GMT
content-type: application/json
content-length: 1831
server: Pathfinder
</pre>

Example response body:
<pre class=include-code>
path: examples/list-footprints-response.json
highlight: json
</pre>

</div>



### Example Error Response ### {#api-error-response-example}

<div class=example>

Example request:

<pre highlight=http>
GET /0/footprints HTTP/2
host: api.pathfinder.sine.dev
</pre>

Example response headers:

```http
HTTP/1.1 403 Forbidden
date: Mon, 23 May 2022 19:33:16 GMT
content-type: application/json
content-length: 44
server: Pathfinder
```
Example response body:
<pre class=include-code>
path: examples/error-response-access-denied.json
highlight: json
</pre>

</div>


# Appendix A: License # {#license}

<pre class=include>
path: ../../LICENSE.md
</pre>