Merge pull request #284 from papinet/hotfix/supporting-files-Lars

Let's merge the `hotfix/supporting-files-Lars` branch into the `main` branch

Author: robertalivan

CONTRIBUTING.md

@@ -1,9 +1,25 @@
-<!-- Copyright 2000-2024 Papinet SNC ("papiNet") the "Copyright Owner". All rights reserved by the Copyright Owner under the laws of the United States, Belgium, the European Economic Community, and all states, domestic and foreign. For support, more information, or to report implementation bugs, please contact papiNet at https://github.com/papinet. -->
+Copyright 2000 - 2026 the Confederation of European Paper Industries AISBL ("papiNet") the "Copyright Owner". All rights reserved by the Copyright Owner under the laws of the United States, Belgium, the European Economic Community, and all states, domestic and foreign. For support, more information, or to report implementation bugs, please contact papiNet at https://github.com/papinet.
 
 # Contributing Guidelines
 
 This document intends to establish guidelines which build a transparent, open mechanism for deciding how to evolve the papiNet API standard. The papiNet Central Working Group (CWG) will follow these processes when merging changes from external contributors or from the CWG itself. This guideline document will be adjusted as practicality dictates.
 
+## Use of GitHub issues
+
+Issues are created for tracking of decisions and changes.
+
+* Issues should be assigned to responsible maintainers, so that they get notifications when issues are updated or commented.
+
+* Issues should be given appropiate labels when updated or commented.
+
+* Solutions for issues are approved, approved with amendment or rejected by CWG.
+
+* Implementation of a solution for an issue should have one or several commits. No other changes should exist in these commits. The commits should have a reference to the issue number. A description of the change and a link to the commits should be given in a comment of the issue.
+
+* Implementation of a solution for an issue should be reviewed by at least one maintainer.
+
+* Issues are closed at CWG API meetings.
+
 ## Tracking Process
 
 GitHub is the medium of record for all papiNet API standard updates.

FAQ.md

@@ -1,4 +1,4 @@
-<!-- Copyright 2000-2024 Papinet SNC ("papiNet") the "Copyright Owner". All rights reserved by the Copyright Owner under the laws of the United States, Belgium, the European Economic Community, and all states, domestic and foreign. For support, more information, or to report implementation bugs, please contact papiNet at https://github.com/papinet. -->
+Copyright 2000 - 2026 the Confederation of European Paper Industries AISBL ("papiNet") the "Copyright Owner". All rights reserved by the Copyright Owner under the laws of the United States, Belgium, the European Economic Community, and all states, domestic and foreign. For support, more information, or to report implementation bugs, please contact papiNet at https://github.com/papinet.
 
 # Frequently Asked Questions (FAQ)
 

GOVERNANCE.md

@@ -1,4 +1,4 @@
-<!-- Copyright 2000-2024 Papinet SNC ("papiNet") the "Copyright Owner". All rights reserved by the Copyright Owner under the laws of the United States, Belgium, the European Economic Community, and all states, domestic and foreign. For support, more information, or to report implementation bugs, please contact papiNet at https://github.com/papinet. -->
+Copyright 2000 - 2026 the Confederation of European Paper Industries AISBL ("papiNet") the "Copyright Owner". All rights reserved by the Copyright Owner under the laws of the United States, Belgium, the European Economic Community, and all states, domestic and foreign. For support, more information, or to report implementation bugs, please contact papiNet at https://github.com/papinet.
 
 # Governance
 

LICENSE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2000-2024 Papinet SNC ("papiNet") the "Copyright Owner". All rights reserved by the Copyright Owner under the laws of the United States, Belgium, the European Economic Community, and all states, domestic and foreign. For support, more information, or to report implementation bugs, please contact papiNet at https://github.com/papinet.
+   Copyright 2000 - 2026 the Confederation of European Paper Industries AISBL ("papiNet") the "Copyright Owner". All rights reserved by the Copyright Owner under the laws of the United States, Belgium, the European Economic Community, and all states, domestic and foreign. For support, more information, or to report implementation bugs, please contact papiNet at https://github.com/papinet.
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

MAINTAINERS.md

@@ -1,4 +1,4 @@
-<!-- Copyright 2000-2024 Papinet SNC ("papiNet") the "Copyright Owner". All rights reserved by the Copyright Owner under the laws of the United States, Belgium, the European Economic Community, and all states, domestic and foreign. For support, more information, or to report implementation bugs, please contact papiNet at https://github.com/papinet. -->
+Copyright 2000 - 2026 the Confederation of European Paper Industries AISBL ("papiNet") the "Copyright Owner". All rights reserved by the Copyright Owner under the laws of the United States, Belgium, the European Economic Community, and all states, domestic and foreign. For support, more information, or to report implementation bugs, please contact papiNet at https://github.com/papinet.
 
 ## Voting Maintainers
 

NOTICE.md

@@ -1,4 +1,4 @@
-<!-- Copyright 2000-2024 Papinet SNC ("papiNet") the "Copyright Owner". All rights reserved by the Copyright Owner under the laws of the United States, Belgium, the European Economic Community, and all states, domestic and foreign. For support, more information, or to report implementation bugs, please contact papiNet at https://github.com/papinet. -->
+Copyright 2000 - 2026 the Confederation of European Paper Industries AISBL ("papiNet") the "Copyright Owner". All rights reserved by the Copyright Owner under the laws of the United States, Belgium, the European Economic Community, and all states, domestic and foreign. For support, more information, or to report implementation bugs, please contact papiNet at https://github.com/papinet.
 
 # Trademark and Logo Policies
 

README.md

@@ -1,4 +1,5 @@
-<!-- Copyright 2000-2024 Papinet SNC ("papiNet") the "Copyright Owner". All rights reserved by the Copyright Owner under the laws of the United States, Belgium, the European Economic Community, and all states, domestic and foreign. For support, more information, or to report implementation bugs, please contact papiNet at https://github.com/papinet. -->
+Copyright 2000 - 2026 the Confederation of European Paper Industries AISBL ("papiNet") the "Copyright Owner". All rights reserved by the Copyright Owner under the laws of the United States, Belgium, the European Economic Community, and all states, domestic and foreign. For support, more information, or to report implementation bugs, please contact papiNet at https://github.com/papinet. <br/><br/>
+
 
 <!-- markdownlint-disable MD041 -->
 
@@ -46,13 +47,21 @@ The following API endpoints allows a _supplier_ to communicate to a _logistics s
 * `PUT /logistics-delivery-notes/{logisticsDeliveryNoteId}`
 * `POST /logistics-goods-receipts`
 * `PUT /logistics-goods-receipts/{logisticsGoodsReceiptId}`
-* `GET /delivery-instructions`
-* `GET /delivery-instructions/{deliveryInstructionId}`
+* `GET /logistics-delivery-instructions`
+* `GET /logistics-delivery-instructions/{deliveryInstructionId}`
+
+### Warehouse Logistics Inventory Change Use Case
+
+The following API endpoints allows a _supplier_ to communicate inventory changes with a _logistics supplier_:
+
+* `GET /logistics-inventory-changes`
+* `GET /logistics-inventory-changes/{logisticsInventoryChangeId}`
+* `POST /logistics-inventory-changes`
 
 ## The papiNet API Standard
 
 The following normative document is available:
 
-* [`papiNet-API.yaml`](3.0.0/papiNet-API.yaml) the OpenAPI document describing the papiNet API. This is the main normative document.
+* [`papiNet-API.yaml`](4.0.0/papiNet-API.yaml) the OpenAPI document describing the papiNet API. This is the main normative document.
 
-In addition to these normative documents, we also have a papiNet mock service that provides live responses in line with the scenarios described within the use case documents.
+In addition to these normative documents, papiNet also has a **papiNet stub service** that provides live responses in line with the scenarios described within the use case documents.

papiNet-JSON-Style-Guide.md

@@ -0,0 +1,103 @@
+Copyright 2000 - 2026 the Confederation of European Paper Industries AISBL ("papiNet") the "Copyright Owner". All rights reserved by the Copyright Owner under the laws of the United States, Belgium, the European Economic Community, and all states, domestic and foreign. For support, more information, or to report implementation bugs, please contact papiNet at https://github.com/papinet.
+
+# papiNet JSON Style Guide
+
+## Introduction
+
+This style guide documents guidelines and recommendations for designing JSON structures for the papiNet API. It clarifies and standardizes specific cases so that all JSON structures used by the papiNet API have a standard look and feel. These guidelines are applicable to JSON requests and responses.
+
+## Definitions
+
+For the purposes of this style guide, papiNet defines the following terms:
+
+* **_property_** - a name/value pair inside a JSON object.
+* **_property name_** - the name portion of the property, also called **_key_**.
+* **_property value_** - the value portion of the property, sometimes simply called **_value_**.
+
+So, within the following example:
+
+```json
+{
+  "propertyName": "propertyValue",
+  "anotherPropertyName": "anotherPropertyValue"
+}
+```
+
+It's the `"propertyName": "propertyValue"` part, that papiNet calls a _property_.
+
+## Design Rules
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119](https://datatracker.ietf.org/doc/html/rfc2119).
+
+### Rule 0 - Naming convention for properties
+
+If the context is clearly given by the parent, DO NOT repeat the context in the property name; If the context is NOT adequately given by the parent, then DO give the context in the property name up to what is necessary.
+
+Let's give an example of each case:
+
+* within `supplierOrders[]`, `supplierOrderNumber` should become `number` because its parent `supplierOrders[]` is giving the context.
+
+* within `supplierOrders[]`, `purchaseOrderNumber` should NOT become `number` because its parent `supplierOrders[]` is NOT giving the right context, it is not the `number` (identifier) of the `supplierOrders[]`, but of the `number` (identifier) of `purchaseOrders[]`.
+
+### Rule 1
+
+papiNet restrict enumerated values to the minimum list that applies within the context. As a consequence, objects will be usually be defined **locally**! However, if a structure can be reuse whatever the context is, it could be defined globally.
+
+### Rule 2 - How to handle empty collection
+
+An empty collection MUST be communicated via the HTTP status code `204 No Content` and the response MUST NOT contain a response's body. This rule will be enforced by not allowing empty array in the non-empty response's body using `minItems: 1`.
+
+### Rule 3 - minLength of property with type `string`
+
+When papiNet defines a property with type `string` required, papiNet ALWAYS means that this property MUST communicate a non-empty information, therefore the constraint `minLength: 1` will always be added.
+
+When a property with type `string` is not required and there is no information to be communicated, the property MUST NOT appear in the response's body. That rule will be enforced by always add the constraint `minLength: 1` to all properties with type `string`.
+
+This `minLength: 1` constraint will not be added to the property with type `string` that already has such a constraint via `enum` or `format`. Of course, more restrictive constraint with more than 1 character minimum can be defined, but not less!
+
+### Rule 4 - maxLength of property with type `string`
+
+papiNet does not set a `maxLength` to all properties with type `string` driven by system technical constraints. papiNet only sets a `maxLength` to a property with type `string` when it is driven by a business constraint!
+
+### Rule 5 - The response body always contains the full representation of the resource
+
+The response body always contains the full representation of the resource, including the `id` even if it is already part of the request (usually conveyed by the URL).
+
+### Rule 6 - Avoid lookup optimization
+
+When a response contains the reference to something (e.g. a _seller-product_), it MUST only contain the identifier of that thing and any additional information MUST be retrieved via a subsequent lookup. There should not be any lookup optimization combining the identifier with additional information.
+
+### Rule 7 - Array MUST be defined to have at least one element
+
+When papiNet defines a property of type `array`, papiNet ALWAYS means that this array MUST have at least one element; therefore the constraint `minItems: 1` will always be added.
+
+### Rule 8 - Response payload size SHOULD always be minimized
+
+... (with the execption of the `id`)
+
+### Rule 9 - UUID (only) as resource IDs
+
+We MUST use UUID (only) for resource ID defined by the `id` property of every resource/entity/object.
+
+When referring to another resource/entity/object we MUST also use this UUID only, therefore, to be able to know which type of resource/entity/object this UUID refers to, we MUST name of property or one of its ancestors including the type of resource/entity/object.
+
+### Rule 10 - Properties with `...Timestamp` and `...DateTime` suffixes
+
+We have two types of properties capturing date and time:
+
+* The properties ending with the suffix `...Timestamp`: the MUST contain a date and time expressed in UTC, ending with the letter "Z", e.g. `2024-04-23T13:24:26.000Z`.
+* The properties ending with the suffix `...DateTime`: they MUST contain a local date and time, in accordance with the ISO 8601 standard (preferably without explicit time-zone) for which the location is defined by the business context, excluding duration alone, but including intervals such as the following:
+  - `2023-08-16T13:00/2023-08-18T13:00`
+  - `2023-08-16/2023-08-18`
+  - `2023-08-16T13:00/P2D`
+  - `P2D/2023-08-18T13:00 `
+
+### Rule 11 - JSON properties format
+
+JSON properties MUST be written in lowerCamelCase names capitalize the first letter of each word, except the first which is always lowercase, **even if it's an acronym**. For instance, we have the property `coordinatesWgs84:` where `Wgs` stands for "World Geodetic System".
+
+### Rule 12 - Avoid abbreviations
+
+All names specified in path and query parameters, resource names, and JSON input and output fields and pre-defined values SHOULD NOT use abbreviations or acronyms.
+
+However, we have decided, during papiNet CWG meeting 2024-06-19 (Wed), to make an exception with "unit of measure" that we will write `uom` or `(...)Uom`, instead of `unitOfMeasure` or `(...)UnitOfMeasure`.

tools/README.md

@@ -1,6 +1,52 @@
+Copyright 2000 - 2026 the Confederation of European Paper Industries AISBL ("papiNet") the "Copyright Owner". All rights reserved by the Copyright Owner under the laws of the United States, Belgium, the European Economic Community, and all states, domestic and foreign. For support, more information, or to report implementation bugs, please contact papiNet at https://github.com/papinet.
+
 ## Tools
 
-This `tools/` folder does contain a few tools/scripts that help us to develop the papiNet API standard.
+The `tools/` folder serves as a repository for some tools.  
+papiNet makes no guarantees regarding the functionality, performance or suitability of these tools.
+
+### How to install the _Standalone Pact Stub Server_ on Windows (without administrative rights)
+
+1\. Download the archive `pact-stub-server-windows-x86_64.exe.gz` containing the latest version of the binary `pact-stub-server.exe` at https://github.com/pact-foundation/pact-stub-server/releases into your `\Downloads` folder.
+
+***Note:*** You might have to click on the "Show all __ assets" link!
+
+2\. Using the File Explorer, create a new subfolder `Pact` within the folder `C:\Users\{Username}\AppData\Local\Programs`.
+
+3\. Unzip/Extract the file `pact-stub-server.exe` from the `pact-stub-server-windows-x86_64.exe.gz` archive into the folder `C:\Users\{Username}\AppData\Local\Programs\Pact`.
+
+4\. From a Windows Command Prompt run the following command:
+
+```text
+rundll32.exe sysdm.cpl,EditEnvironmentVariables
+```
+
+5\ . From the "User variables for {Username}" section, click on the "New..." button to create a new variable with the name `PACT_BIN` and the value `C:\Users\{Username}\AppData\Local\Programs\Pact`.
+
+6\. From the "User variables for {Username}" section, select the `Path` variable and click on the "Edit.." button, then click on the "New" button and add the line `%PACT_BIN%` at the end.
+
+7\. From a new Windows Command Prompt run the following command to verify the installation:
+
+```text
+pact-stub-server --version
+```
+
+If all went well, you should get a response like this one:
+
+```text
+pact stub server version  : v0.7.0
+pact specification version: v4.0
+```
+
+### `analyse-uom.js`
+
+This script will list all the `uom` (unit of measure) within the schemas of the papiNet API OpenAPI documentation.
+
+```text
+node analyse-uom.js
+```
+
+
 
 ### `analyse-uom.js`