-
Notifications
You must be signed in to change notification settings - Fork 12
/
Copy pathopenapi.yaml
1862 lines (1737 loc) · 77.8 KB
/
openapi.yaml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
openapi: 3.1.0
info:
title: PACT API Specification
summary: Technical Specifications for PCF Data Exchange
version: 3.0.0
contact:
name: WBCSD PACT Project
url: https://github.com/wbcsd
email: [email protected]
description: |
This document describes the technical specifications for the exchange of
Product Carbon Footprint (PCF) data between systems. The specification is
maintained by the WBCSD PACT project and intended to be used by organizations
that wish to exchange PCF data with other organizations. The specifications
are designed to be technology-agnostic.
tags:
- name: footprint
description: Synchronous retrieval of footprints
- name: event
description: Asynchronous Event API. This API is used to post events to the system.
Data recipients can request footprints and will receive notifications when these requests are fulfilled or rejected.
Data owners can post updated and newly published footprints to data recipients.
servers:
- url: https://example.com
paths:
/3/footprints:
get:
summary: Action ListFootprints
description: |
Retrieve a list of Product Carbon Footprints (PCFs) from the [=data owner=].
The [=data recipient=] can specify various criteria to filter the
list, and the [=data owner=] can paginate the result set, if necessary.
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.
If the host system has multiple versions of the same footprint with the
same `id`, it MUST include only the latest version in the list of
footprints. The host system SHOULD include preceding footprints which have
been deprecated in the resulting list of footprints, except if the `status`
query parameter explicity requests only active footprints.
### Pagination
1. The host system MUST NOT return more product footprints than requested in
case a <{listFootprints/limit}> parameter was specified by a [=data recipient=]
2. The host system MUST return an HTTP `Link` header if there are additional
ProductFootprints ready to be retrieved, such that
- The `Link` header conforms to [[!RFC8288]]
- The value of the `rel` parameter is equal to `next`
- the target URI of the `Link` header is absolute
- The value of `host` of the target URI is equal to the value of the `host`
request header from the original `ListFootprints` HTTP request
3. The target URI from the `Link` header is called a <dfn>pagination link</dfn>.
4. A pagination link MUST be valid for at least 180 seconds after creation
5. The data recipient CAN call the pagination link more than once
6. Upon each call, the host system
- MUST return the same set of Product Footprints
- MUST NOT return more product footprints than requested in case
<{listFootprints/limit}> was defined by a [=data recipient=]
- MUST return a `Link` header conforming with the previous description in case
there are additional ProductFootprints available
```http
link: <https://api.example.com/3/footprints?geography=FR&limit=10&offset=10>; rel="next"
```
7. If a response contains a second pagination link and the data recipient has called
that second pagination link, the previous pagination link MAY no longer work: data
recipients MUST NOT assume that previous pagination links continue to return results
after advancing in the pagination process.
### Filtering
The [=host system=] MUST support filtering of the list of footprints by
criteria described under Parameters. Note that these are the same filters
used by the [[#request-created-event]] Event.
A host system MAY provide additional filter criteria for the data recipient
to use. These parameters MUST be prefixed with `x-<identifier>-`.
For example, to add functionality to search for product
footprints based on an invoice number, a software solution could choose
to support a parameter `x-atq-invoice-id`.
```http
/3/footprints/?geography=FR&x-atq-invoice-id=12345&limit=100
```
tags: [footprint]
parameters:
- name: limit
description: |
The maximum number of footprints to return. The [=host system=] MAY return fewer
footprints, but MUST return a Link header conforming to [[!RFC8288]] if there are
additional ProductFootprints ready to be retrieved.
in: query
schema:
type: integer
format: uint
minimum: 0
- $ref: '#/components/parameters/productId'
- $ref: '#/components/parameters/companyId'
- $ref: '#/components/parameters/geography'
- $ref: '#/components/parameters/classification'
- $ref: '#/components/parameters/validOn'
- $ref: '#/components/parameters/validAfter'
- $ref: '#/components/parameters/validBefore'
- $ref: '#/components/parameters/status'
- name: '$filter'
in: query
description: |
Syntax as defined by the ODatav4 specification. Note: this parameter has been deprecated in 3.0.0.
allowEmptyValue: true
schema:
type: string
deprecated: true
responses:
'200':
description: |
The host system succesfully returns a list of product footprints. This list
MAY be incomplete, in which case the host system MUST return a Link header
conforming to [[!RFC8288]], also see [[#pagination]]. The list MUST NOT be
larger than the <{listFootprints/limit}>, if specified.
```http
HTTP/1.1 200 OK
link: <https://api.example.com/3/footprints?geography=FR&limit=10&offset=10>; rel="next"
content-type: application/json
```
```json
{
"data": [
{"id": "079e425a-464f-528d-341d-4a944a1dfd70", ... },
{"id": "f4b1225a-bd44-4c8e-861d-079e4e1dfd69", ... }
...
]
}
```
The list MAY also be empty. If the list is empty, the host system MUST return an empty
JSON array. The list MUST NOT be NULL.
```json
{
"data": [] // MUST NOT be null
}
```
headers:
link:
description: Link header to next result set. See [[#pagination]].
schema:
type: string
examples:
- "https://api.example.com/3/footprints?[...]"
content:
application/json:
schema:
type: object
required:
- data
properties:
data:
description: List of <{ProductFootprint}> objects.
type: array
minItems: 0
items:
$ref: '#/components/schemas/ProductFootprint'
'400':
$ref: '#/components/schemas/BadRequestResponse'
'401':
$ref: '#/components/schemas/UnauthorizedResponse'
'403':
$ref: '#/components/schemas/ForbiddenResponse'
'500':
$ref: '#/components/schemas/InternalErrorResponse'
security:
- BearerAuth: []
/3/footprints/{id}:
get:
summary: Action GetFootprint
description: |
Retrieve a single Product Carbon Footprint (PCF) by its unique identifier.
If the host system has multiple versions of the same footprint with the
same `id`, it MUST include only the latest version in the list of footprints.
If the requested ProductFootprint is deprecated, the host system SHOULD
return the deprecated ProductFootprint, if it is still available.
If the requested ProductFootprint is not found, the host system MUST return
a 404 Not Found response.
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.
If it determines that a data recipient is not allowed to access the requested
ProductFootprint, the host system MUST return a 403 Forbidden response.
tags: [footprint]
parameters:
- name: id
description: The value of property id of a product footprint a data recipient intends to retrieve.
in: path
required: true
schema:
type: string
format: uuid
responses:
'200':
description: |
Indicates success: the product footprint was found and returned
by the host system.
Example response body:
```json
{
"data": {
"id": "079e425a-464f-528d-341d-4a944a1dfd70",
"productIds": ["urn:pact:sample.com:product-id:44055-9c05bc35-68f8"]},
"productNameCompany": "Sample Product",
...
}
}
```
content:
application/json:
schema:
type: object
required:
- data
properties:
data:
description: |
The product footprint requested, see <{ProductFootprint}>.
$ref: '#/components/schemas/ProductFootprint'
'400':
$ref: '#/components/schemas/BadRequestResponse'
'401':
$ref: '#/components/schemas/UnauthorizedResponse'
'403':
description: |
The data recipient is not allowed to access the requested ProductFootprint.
Response body MUST contain a JSON <{Error}> object
$ref: '#/components/schemas/ForbiddenResponse'
'404':
description: |
The requested ProductFootprint was not found.
Response body MUST contain a JSON <{Error}> object
$ref: '#/components/schemas/NotFoundResponse'
'500':
$ref: '#/components/schemas/InternalErrorResponse'
security:
- BearerAuth: []
/3/events:
post:
summary: Action Events
description: |
The Action Events endpoint supports the following use cases:
1. enabling a [=data recipient=] to request Product Footprints
from a [=data owner=] by sending a `RequestCreatedEvent`, to
which the data owner can answer by sending `RequestFulfilledEvent`
or a `RequestRejectedEvent`.
2. enabling a [=data owner=] to notify a [=data recipient=] on
updates to 1 or more Product Footprints: `PublishedEvent`
The Action Events endpoint accepts CloudEvent events (see [[!CE]]) encoded
in "Structured Content Mode" (see [[!CE-Structured-Content-Mode]]).
The CloudEvents are encoded in the "application/cloudevents+json" media type and
MUST be sent as an HTTP POST request body to the Action Events endpoint.
The following events MUST be handled by the host system:
- [`RequestCreatedEvent`](#request-created-event)
- [`RequestFulfilledEvent`](#request-fulfilled-event)
- [`RequestRejectedEvent`](#request-rejected-event)
- [`PublishedEvent`](#productfootprint-published-event)
A host system MUST validate the event and return an HTTP 4xx status code if the
event is invalid.
Upon accepting the event, the [=host system=] MUST return an HTTP 200 status code
and SHOULD return an empty response body.
tags: [event]
requestBody:
content:
application/cloudevents+json:
schema:
oneOf:
- $ref: '#/components/schemas/RequestCreatedEvent'
- $ref: '#/components/schemas/RequestFulfilledEvent'
- $ref: '#/components/schemas/RequestRejectedEvent'
- $ref: '#/components/schemas/PublishedEvent'
responses:
'200':
description: |
Indicates success: the event was accepted by the host system. The response
body will be empty.
'400':
$ref: '#/components/schemas/BadRequestResponse'
'401':
$ref: '#/components/schemas/UnauthorizedResponse'
'403':
$ref: '#/components/schemas/ForbiddenResponse'
'500':
$ref: '#/components/schemas/InternalErrorResponse'
security:
- BearerAuth: []
components:
schemas:
ProductFootprint:
description: |
`ProductFootprint` is a data type which represents the carbon footprint
of a product under a specific scope ([[#dt-carbonfootprint-scope]])
and with values calculated in accordance with the [=PACT Methodology=].
The objective of a `ProductFootprint` is to provide interoperability between
the creator (the [=data owner=]) and the consumer (the [=data recipient=]) of
ProductFootprints. The details on the exchange of ProductFootprints are
specified in [[#api]].
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=].
Data Model Extensions enable [=data owners=] to exchange additional information
related to a product with [=data recipients=]. The details are specified
in [[#datamodelextension]] as well as [[!EXTENSIONS-GUIDANCE]], and [[!DATA-MODEL-EXTENSIONS]].
Each `ProductFootprint` can and should be updated over time, for instance to
incorporate new or refined data from [=data owners=] (see [[#lifecycle]]).
summary: |
The ProductFootprint represents the footprint of a product.
type: object
title: ProductFootprint
required:
- id
- specVersion
- version
- created
- status
- companyName
- companyIds
- productDescription
- productIds
- 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 solution to maintain
the required technical references to data within the system.
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. "3.0.0").
type: string
pattern: '^\d+\.\d+\.\d+(-\d{8})?$'
examples:
- "3.0.0"
precedingPfIds:
description: |
A given PCF may change over time, due to updates to the calculation.
This is a list of IDs that reflect "past versions" of the current PCF,
maintained by the solution.
See [[#lifecycle]] for details.
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. Starting 3.0, any change to a
PCF will generate a new ID, so this field is no longer needed.
See [[#lifecycle]] for details.
note: Deprecated in 3.0. MUST be 1.
type: integer
format: int32
minimum: 0
created:
description: |
The date and time when the PCF was created. This is typically an automatically
generated field by the solution. It SHOULD NOT be used to derive status of
validity of the PCF.
See [[#lifecycle]] for details.
type: string
format: date-time
examples:
- '2024-10-31T00:00:00Z'
updated:
description: |
The date and time when the PCF was last updated. Starting 3.0 any change to
a PCF will generate a new ProductFootprint, which is immutable, leaving
the updated property redundant.
See [[#lifecycle]] for details.
note: Deprecated in 3.0.
type: string
format: date-time
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 by a data recipients, e.g. for product
footprint calculations. `Deprecated` means that the PCF is no longer
the most recent version and SHOULD NOT be used by data recipients.
See [[#lifecycle]] for details.
type: string
enum:
- Active
- Deprecated
examples:
- Active
validityPeriodStart:
description: |
The start date of the validity period: the time interval during which the
ProductFootprint is declared as valid for use by a receiving [=data recipient=].
If no validity period is specified, the ProductFootprint is valid for 3 years after
the <{CarbonFootprint/referencePeriodEnd}>
See [[#validity-period]] for details.
summary: |
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, starting from the referencePeriodEnd.
type: string
format: date-time
validityPeriodEnd:
description: |
The end date and time of the validity period. After this date the ProductFootprint
is not valid for use anymore. See [[#validity-period]] for more details.
type: string
format: date-time
companyName:
description: |
The name of the company that is the PCF Data Owner
$ref: '#/components/schemas/NonEmptyString'
companyIds:
description: |
The non-empty set of Uniform Resource Names ([[!RFC8141|URN]]). Each value of
this set is supposed to uniquely identify the ProductFootprint Data Owner.
TODO: See Company Identifier section for details
summary: |
A list of company identifiers which represent the companies that are considered
data owners of the 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 Uniform Resource Names ([[!RFC8141|URN]]),
which helps ensure the data provided is standardized and can be interpreted by the
receiving system.
examples:
- ["urn:company:example:company1"]
- ["urn:company:example:company1","urn:company:example:company2"]
type: array
minItems: 1
uniqueItems: true
items:
$ref: '#/components/schemas/Urn'
productDescription:
description: |
The free-form description of the product, including any additional relevant information
such as 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: |
The non-empty set of Product IDs in [[!RFC8141|URN]] format. Each of the values in the set is
supposed to uniquely identify the product. See [[#product-identifier-urns]] for syntax and
examples.
summary: |
All relevant product identifiers to identify the product for which the provided
PCF was calculated (e.g. supplier part number, GTIN, article number, batch number, etc.)
type: array
minItems: 1
uniqueItems: true
items:
$ref: '#/components/schemas/Urn'
productClassifications:
description: |
The non-empty set of Product Classifications in [[!RFC8141|URN]] format. Each of the values
in the set can classify the product as part of distinct groupings and categorizations.
See [[#product-classification-urns]].
note: Replaces productCategoryCpc deprecated in 2.3
summary: |
A list of classification or category identifiers in URN format. Use well known urn's here,
or adhere to recommended urn:pact: format. For example UN CPC, CAS Numbr, CN Code etc.
This replaces the productCategoryCpc property from 2.0.
type: array
minItems: 1
uniqueItems: true
items:
$ref: '#/components/schemas/Urn'
examples:
- ["urn:pact:productclassification:un-cpc:1234"]
- ["urn:pact:productclassification:un-cpc:1234", "urn:pact:productclassification:cas:1234"]
productNameCompany:
description: |
The name with which the company producing the product refers to it, i.e. the product's trade name.
Recognizable by the receiver of the PCF information.
$ref: '#/components/schemas/NonEmptyString'
comment:
description: |
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.
note: optional in 3.0, was mandatory in 2.x
summary: |
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.
Information explaining the current status of the PCF, what was changed since the last version, etc. If the PCF was changed since a previous version, indicate all methodological and/or production process change(s) that occurred to result in the PCF change. For example, include the relevant change(s) from the list below:
1. In case product or sector specific guidance used does not align with PACT Methodology's requirement, the areas of disalignment should be specified in the comment section (e.g. allocation rules, exemption rules, data quality metrics).
2. Information explaining the current status of the PCF, what was changed since the last version, etc. If the PCF was changed since a previous version, indicate all methodological and/or production process change(s) that occurred to result in the PCF change. E.g., include the relevant change(s) from the list below:
Methodological:
- Access to new Emission Factor data (database, supplier-specific, company-specific)
- Updated upstream data (i.e. upstream supplier updated their PCF based on methodology change)
Production Process:
- Change in process
- Change in feedstock
- Change from conventional to certified sustainable material
- Change in energy source
- Change in upstream supplier
- Updated upstream data (i.e. upstream supplier updated their PCF based on process change)
3. Additional information on biogenic emissions & removals calculation should be specified. This includes information on tools used for calculations (e.g. Cool Farm Tool), and methodological choices made in calculation of biogenic emissions and removals (e.g. Statistical or Direct Land use change calculation for DLUC calculations).
type: string
pcf:
description: |
The carbon footprint of the given product with value conforming to the data
type <{CarbonFootprint}>.
summary:
The carbon footprint of the given product.
$ref: '#/components/schemas/CarbonFootprint'
extensions:
type: array
description: |
If defined, 1 or more data model extensions associated with the ProductFootprint.
See <{DataModelExtension}> for details.
items:
$ref: '#/components/schemas/DataModelExtension'
CarbonFootprint:
description: |
A CarbonFootprint represents the carbon footprint of a product and related data in accordance with the [=PACT Methodology=].
### Scope of a CarbonFootprint ### {#dt-carbonfootprint-scope}
Each CarbonFootprint is scoped by
1. Time Period: the time period is defined by the properties <{CarbonFootprint/referencePeriodStart}> and <{CarbonFootprint/referencePeriodEnd}> (see [=PACT Methodology=] section 6.1.2.1)
2. Geography: further set by the properties <{CarbonFootprint/geographyRegionOrSubregion}>, <{CarbonFootprint/geographyCountry}>, and <{CarbonFootprint/geographyCountrySubdivision}> (see [=PACT Methodology=] section 6.1.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`.
summary: |
The CarbonFootprint represents the carbon footprint of a product and related data
in accordance with the PACT Methodology.
title: CarbonFootprint
type: object
required:
- declaredUnitOfMeasurement
- declaredUnitAmount
- productMassPerDeclaredUnit
- referencePeriodStart
- referencePeriodEnd
- pcfExcludingBiogenicCO2Withdrawal
- pcfIncludingBiogenicCO2Withdrawal
- fossilGhgEmissions
- fossilCarbonContent
- biogenicCarbonContent
- ipccCharacterizationFactors
- crossSectoralStandards
- exemptedEmissionsPercent
# oneOf:
# - oneOf:
# - required:
# - geographyRegionOrSubregion
# - required:
# - geographyCountry
# - required:
# - geographyCountrySubdivision
# - not:
# anyOf:
# - required:
# - geographyRegionOrSubregion
# - required:
# - geographyCountry
# - required:
# - geographyCountrySubdivision
properties:
declaredUnitOfMeasurement:
description: |
The unit of measurement of the product. Together with `declaredUnitAmount`
this defines the 'declared unit' of the product. Emissions in this carbon
footprint are expressed in kgCO2e per 'declared unit'.
For example: a PCF for a 12 liter bottle of Ethanol states 2 kg of CO2e in
emissions. In this case the declared unit is 12 liter Ethanol, thus the
`declaredUnitOfMeasurement` is 'liter', and the `declaredUnitAmount` is 12.
type: string
enum:
- liter
- kilogram
- cubic meter
- kilowatt hour
- megajoule
- ton kilometer
- square meter
- piece
- hour
- megabit second
declaredUnitAmount:
description: |
The amount of <{CarbonFootprint/declaredUnitOfMeasurement|units}> contained
within the product to which the [[#carbonfootprint|PCF]] is referring.
For example: if the product is a car door weighing 80kg, `declaredUnitAmount`
will be `80` and `declaredUnitOfMeasurement` will be `kilogram`.
summary: |
The amount of units contained within the product to which the PCF refers.
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, the value MUST be 1)
x-unit: declared unit
$ref: '#/components/schemas/PositiveNonZeroDecimal'
productMassPerDeclaredUnit:
description: |
The mass (in kg) of the product excluding packaging. The 'declared unit' is
the `declaredUnitAmount` times `declaredUnitOfMeasurement`.
For example, if the declared unit is `piece`, this attribute MUST be populated
with the mass of `declaredUnitAmount` pieces of the product. If the declared unit
is `liter`, this attribute MUST be populated with the mass of `declaredUnitAmount`
liters of the product.
If the product mass is not relevant (i.e. PCF is for an energy (kWh, MJ),
logistics (ton.km) or service related product), this attribute SHOULD be populated
with `0`.
note: mandatory in 3.0, optional in v2.x
$ref: '#/components/schemas/Decimal'
pcfExcludingBiogenicCO2Withdrawal:
description: |
The PCF of the product including:
- all emissions from fossil sources
- all biogenic and land management-related CH4, N2O, non-biogenic CO2, HFCs and PFCs emissions
- land management CO2 removals
Excluding:
- all biogenic CO2 withdrawals.
x-unit: kgCO2e/declared unit
x-comment: |
PCF (Excl. biogenic CO2 withdrawal) = fossilGhgEmissions + landUseChangeGhgEmissions + landManagementBiogenicCO2Emissions + biogenicNonCO2Emissions + landManagementBiogenicCO2Removals
x-rule: M3, M2-2025
$ref: '#/components/schemas/Decimal'
pcfIncludingBiogenicCO2Withdrawal:
description: |
The PCF of the product including:
- all emissions from fossil sources
- all biogenic and land management-related CH4, N2O, non-biogenic CO2, HFCs and PFCs emissions
- land management CO2 removals
- all biogenic CO2 withdrawals.
x-unit: kgCO2e/declared unit
x-comment: |
PCF (Incl. biogenic CO2 withdrawal) = FossilGHGEmissions + landUseChangeGHGEmissions + landManagementBiogenicCO2Emissions + biogenicNonCO2Emissions + landManagementBiogenicCO2Removals + biogenicCO2Withdrawal
x-rule: M3, M2-2025
$ref: '#/components/schemas/Decimal'
fossilGhgEmissions:
description: |
The emissions from fossil sources as a result of fuel combustion, from
fugitive emissions, and from process emissions.
Expressed in kgCO2e per declared unit.
summary: |
The emissions from fossil sources as a result of fuel combustion, from fugitive
emissions, and from process emissions.
x-unit: kgCO2e/declared unit
x-rule: M
$ref: '#/components/schemas/PositiveOrZeroDecimal'
fossilCarbonContent:
description: |
The fossil carbon content of the product (mass of carbon).
x-unit: kgC/declared unit
x-rule: M
$ref: '#/components/schemas/PositiveOrZeroDecimal'
biogenicCarbonContent:
description: |
The biogenic carbon content of the product (mass of carbon).
x-unit: kgC/declared unit
x-rule: M
$ref: '#/components/schemas/PositiveOrZeroDecimal'
landUseChangeGhgEmissions:
description: |
GHG emissions from land-use change, such as deforestation or conversion
from natural forest to plantation forest, that cause carbon stock loss.
x-unit: kgCO2e/declared unit
x-rule: M3, M2-2025
x-comment: Replaces dLucGhgEmissions
$ref: '#/components/schemas/PositiveOrZeroDecimal'
landCarbonLeakage:
description: |
Indirect land use change due to carbon stock losses from conversion of native
ecosystems to agricultural land to replace food production.
x-unit: kgCO2e/declared unit
x-comment: Replaces iLucGhgEmissions
$ref: '#/components/schemas/PositiveOrZeroDecimal'
landManagementBiogenicCO2Emissions:
description: |
Biogenic CO2 emissions occurring due to recurring land management actions on
land within the same land-use category.
x-unit: kgCO2e/declared unit
x-rule: M3-2027
$ref: '#/components/schemas/PositiveOrZeroDecimal'
landManagementBiogenicCO2Removals:
description: |
CO2 removals resulting from a net increase in carbon stored in land-based carbon
pools (e.g. reforestation and afforestation). Subject to traceability requirements.
x-unit: kgCO2e/declared unit
$ref: '#/components/schemas/NegativeOrZeroDecimal'
biogenicCO2Withdrawal:
description: |
Net CO2 uptake of biomass in the product. Withdrawals are expressed in
kgCO2e per declared unit, equal to or less than zero.
x-unit: kgCO2e/declared unit
x-rule: M3, M2-2025
$ref: '#/components/schemas/NegativeOrZeroDecimal'
x-comment: Replaces biogenicCarbonWithdrawal
biogenicNonCO2Emissions:
description: |
Biogenic Non-CO2 emissions (e.g. CH4 & N2O) caused by combustion of biofuels
and composting of biowaste, including agricultural land management activities
such as manure fertilization and enteric emissions.
x-unit: kgCO2e/declared unit
x-rule: M3, M2-2025
$ref: '#/components/schemas/PositiveOrZeroDecimal'
uncertifiedLandManagementCO2Removals:
description: |
Uncertified land management CO2 removals.
x-unit: kgCO2e/declared unit
x-rule: M2-2025
$ref: '#/components/schemas/PositiveOrZeroDecimal'
aircraftGhgEmissions:
description: |
If present, the GHG emissions resulting from aircraft engine usage for the transport of the product, excluding radiative forcing.
x-unit: kgCO2e/declared unit
$ref: '#/components/schemas/PositiveOrZeroDecimal'
packagingGhgEmissions:
description: |
Emissions resulting from the packaging of the product. MUST be undefined if packaging emissions are not included.
$ref: '#/components/schemas/PositiveOrZeroDecimal'
x-unit: kgCO2e/declared unit
outboundLogisticsGhgEmissions:
description: |
Emissions resulting from outbound logistics. MUST be undefined if outbound logistics emissions are not included.
$ref: '#/components/schemas/PositiveOrZeroDecimal'
x-unit: kgCO2e/declared unit
ccuCarbonContent:
description: |
The amount of captured carbon (both biogenic and fossil) during CCU (Carbon Capture & Usage) in the production.
$ref: '#/components/schemas/PositiveOrZeroDecimal'
x-unit: kgC/declared unit
ccuOrigin:
description: |
Information about the origin (fossil or biogenic) and path of the captured CO2 used in CCU, including the name and location of the capture facility. This information enhances transparency and traceability, enabling tracking of CO2 across the value chain.
type: string
ccuCalculationApproach:
description: |
The calculation approach for CCU: "Cut-off" or "Credit." See [=PACT Methodology=] for details.
type: string
enum:
- Cut-off
- Credit
ccuCreditCertification:
description: |
(Only for Credit Approach) a URL to documentation verifying the certification from an external bookkeeping scheme.
This attribute ensures the reliability and avoids double counting of credits within the crediting system.
$ref: '#/components/schemas/Uri'
landAreaOccupation:
description: |
Amount of agricultural land occupied in reporting year to produce the product.
x-unit: (m2/annum) / declared unit
$ref: '#/components/schemas/PositiveOrZeroDecimal'
ipccCharacterizationFactors:
description: |
The characterization factors from one or more IPCC Assessment Reports used in the calculation of the PCF (see [=PACT Methodology=] Section 3.2.2).
It MUST be a non-empty set of strings with the format `AR$VERSION$`, where `$VERSION$` stands for the
IPCC report version number and MUST be an integer.
Per the 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.
note: supersedes `characterizationFactors` deprecated in 2.3.
summary: |
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 number 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.
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
items:
type: string
pattern: '^AR\d+$'
minItems: 1
uniqueItems: true
examples:
- ["AR6"]
- ["AR5", "AR6"]
crossSectoralStandards:
description: |
The cross-sectoral standards applied for calculating or allocating [=GHG=] emissions.
It MUST be a non-empty array and SHOULD contain only the following values without duplicates:
: `ISO14067`
:: for the ISO 14067 Standard, "Greenhouse gases — Carbon footprint of products — Requirements and guidelines for quantification"
: `ISO14083`
:: for the ISO 14083 Standard, "Greenhouse gases — Quantification and reporting of greenhouse gas emissions arising from transport chain operations"
: `ISO14040-44`
:: for the ISO 14040-44 Standard, "Environmental management — Life cycle assessment — Principles and framework"
: `GHGP-Product`
:: for the Greehouse Gas Protocol (GHGP) Product Standard
: PEF
:: for the EU Product Environmental Footprint Guide
: `PACT-1.0`
: `PACT-2.0`
: `PACT-3.0`
:: for a given version of the [=PACT Methodology=]. It is recommended to use the latest version of the Methodology.
: PAS2050
:: for the Publicly Available Specification (PAS) 2050, "Specification for the assessment of the life cycle greenhouse gas emissions of goods and services". The use of this standard is permitted but not recommended.
The enumeration of standards above CAN evolve in future revisions. A host system MUST accept ProductFootprints from later revisions with `crossSectoralStandards` containing values that are not defined in this specification.
note: Supersedes `crossSectoralStandardsUsed` deprecated in version 2.3.
summary: |
The cross-sectoral standards applied for calculating or allocating GHG
emissions. If multiple apply, list all.
type: array
items:
type: string
enum:
- ISO14067
- ISO14083
- ISO14040-44
- GHGP-Product
- PEF
- PACT-1.0
- PACT-2.0
- PACT-3.0
minItems: 1
uniqueItems: true
examples:
- [ISO14067, PACT-3.0]
productOrSectorSpecificRules:
description: |
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.
summary: |
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
note: Multiple ProductOrSpecificRules can be specifed, each with its own operator and ruleNames.
examples:
-
- operator: PEF
ruleNames:
- "PEF 1.0"
- "PEF 2.0"
- operator: PCR
ruleNames:
- "PCR-A"
biogenicAccountingMethodology:
description: |
UNDER DISCUSSION
type: string
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).
note: optional in 3.0, was mandatory in 2.x
type: string
referencePeriodStart:
description: |
The start (including) of the time boundary for which the PCF value
is considered to be representative. Specifically, this start date
represents the earliest date from which activity data was collected
to include in the PCF calculation.
summary: |
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 (excluding) of the time boundary for which the PCF value is
considered to be representative. Specifically, this end date
represents the latest date from which activity data was collected
to include in the PCF calculation.
summary: |
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: |
If present, the value MUST conform to data type {{RegionOrSubregion}}. See [[#dt-carbonfootprint-scope]] for further details. Additionally, see the [=PACT Methodology=] Section 6.1.2.2.
summary: |
The geographic representation of the PCF may be reported at different
levels of granularity, depending on the preference of the data owner
(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
examples:
- "Eastern Asia"
- "Southern Europe"
geographyCountry:
description: |
If present, the value MUST conform to data type [=ISO3166CC=]. See [[#dt-carbonfootprint-scope]] for further details.
summary: |
The geographic representation of the PCF may be reported at different levels
of granularity, depending on the preference of the data owner (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