`sellerProduct` structure in `GetSupplierOrderById`, `GetDeliveryNoteById` and `CreateGoodsReceipt` in version 3.0.0

[larsolofsson]

A sellerProduct can be fully defined identified by the property partNumber: or not fully defined identified by the property gradeCode: . The global object Paper needs to be updated to specify the schema also for a not fully specified sellerProduct,

As discussed earlier papiNet should have all properties for paper characteristics in an array similar to what can be found on product specification sheets on web sites of paper companies.

[patricekrakow]

The sellerProduct has the following properties:

sellerProduct
  id? (uuid)
  brandName? (string)
  gradeCode? (string)
  partNumber? (string)
  name? (string)
  paper (Paper) | pulp (Pulp) | ...

Is it clear that providing a partNumber means that the sellerProduct is fully qualified, while providing only a gradeCode means that the sellerProduct is not fully qualified, requiring a new structure for the Paper (sub-)schema? In the past (see issue #69), we discussed the option to have an explicit property fullySpecified: true | false.

I also think it would be nice to discuss sellerProduct together with customerArticle if we want to keep the distinction between product and article we made in https://github.com/papinet/papiNet-API/blob/master/2.0.0/master-data.md#definitions:

A product is owned and defined by the seller. It has several properties such as the basisWeight, the width, a certain percentage of recycled material, and so on. Usually, some of these properties may have multiple possible values, for instance you could choose the basisWeight of your paper from a list of values: 35 g/m², 39 g/m², 42 g/m², ...

An article is owned and defined by the customer. Typically, a customer specifies an individual article from a product in order to narrow down the various properties that may have multiple potential values, ultimately settling on a single value for each.

In order to show that important distinction within the API itself, we will always use the word product together with seller creating the hyphenated word seller-product, and the word article will always be used with customer creating customer-article.

[patricekrakow]

If we want to support "non fully defined/specified" seller-products, we would need to revisit the Paper (2.0.0) structure that can only contain one value per property.

[patricekrakow]

We have to implement the following constraint:

• gradeCode XOR partNumber
• name?
• brandName?

[patricekrakow]

Here is the JSON Schema structure

type: object
anyOf:
    - required:
        - gradeCode
    - required:
        - partNumber
not:
    required:
      - gradeCode
      - partNumber
properties:
  gradeCode:
    type: string
  partNumber:
    type: string

[patricekrakow]

During the papiNet CWG meeting 2024-06-19 (Wed), we decided to

• Remove Product as re-usage schema and to re-define the schemas of sellerProduct and customerArticleNumber locally;
• The (sub-)schema to be used for all sellerProduct should be:

type: object
allOf:
  - oneOf:
      - required:
          - gradeCode
      - required:
          - partNumber
  - oneOf:
      - required:
          - paper
      - required:
          - pulp
properties:
  gradeCode:
    type: string
    minLength: 1
  partNumber:
    type: string
    minLength: 1
  brandName:
    type: string
    minLength: 1
  name:
    type: string
    minLength: 1
  paper:
    $ref: '#/components/schemas/Paper'
  pulp:
    $ref: '#/components/schemas/Pulp'

• The (sub-)schema to be used for all customerArticleNumber should be:

type: object
oneOf:
  - required:
      - gradeCode
  - required:
      - partNumber
properties:
  gradeCode:
    type: string
    minLength: 1
  partNumber:
    type: string
    minLength: 1
  brandName:
    type: string
    minLength: 1
  name:
    type: string
    minLength: 1

[larsolofsson]

There is not a property customerArticleNumber. The (sub-)schema to be used for all customerArticleReference

type: object
oneOf:
  - required:
      - gradeCode
  - required:
      - partNumber
properties:
  gradeCode:
    type: string
    minLength: 1
  partNumber:
    type: string
    minLength: 1
  brandName:
    type: string
    minLength: 1
  name:
    type: string
    minLength: 1

[patricekrakow]

Done, see commit 17658fe.