Endpoint "/devices/{deviceAlias}/processdata/value" -> Conflicting declarations in PDF vs yaml, Conflicting declarations vs examples

[Aleksandar-1]

Downloaded specification from io-link.com downloads:
JSON_Integration_10222_V100_Mar20.zip

contains:

• JSON_Integration_10222_V100_Mar20.pdf
• JSON_for_IO-Link.yaml

Expected:

• The specification in the pdf matches the specification in the yaml
• The specification in the pdf matches the examples in the pdf
• The specification in the yaml matches the examples in the yaml
• Easy to see which behaviour is expected.

Actual:

• None of the above.

For instance endpoint:
"/devices/{deviceAlias}/processdata/value"

Mismatch of specification pdf from yaml:

YML simpletype:

{
    "iolink": {
        "value": {
            "value": 123
        }
    }
}

PDF simpletype:

{
    "iolink": {
        "value": 123
    }
}

---

YML arraytype:

{
    "iolink": {
        "value": {
            "value": [ 0, 1, 2 ]
        }
    }
}

PDF arraytype:

{
    "iolink": {
        "value": [0, 1, 2]
    }
}

Mismatch of pdf specification to pdf example:

In PDF 5.7.5:

Specification says:
(Translated to JSON)

{
    "getdata": {
        "iolink": {                          -> Table 61 Object processDataIOL
            "valid": true,
            "value": {                       ->  Table 72 Object complexParamterValue
                "Pressure": {
                    "value": 1.2
                }
            },
            "iqValue": false
        }
    }
}

But Example 2 aus 5.7.5 states:

{
    "getData": {
        "iolink": {
            "valid": true,
            "value": {
                "Pressure": 1.2
            }
        },
        "iqValue": false
    }
}

Mismatch of yaml specification to yaml example

Examples from Line 2703 in yaml File:

            'Format=byteArray, CQ in IO-Link (only input), IQ in digital output':
              value:
                getData:
                  ioLink:
                    valid: true
                    value:
                      - 12
                      - 22
                      - 216
                setData:
                  iqValue: true

But should be:

            'Format=byteArray, CQ in IO-Link (only input), IQ in digital output':
              value:
                getData:
                  ioLink:
                    valid: true
                    value:
                      value:
                        - 12
                        - 22
                        - 216

Oben: iolink.value: wert,
Unten: iolink.value.value.wert

Note that this issue only is about one single endpoint. The specification has more than two dozens of endpoints. It is a very high effort to find out which behaviour was really intended.

• Is there a following Release of the Speficiation Planned (the current states it is from March 2020) ?
• There is an open issue that states there will be a Version 2.0 (Create PDF document for the V2.0.0 Release #175). Is there a release Date planned for this?

Best regards,
Aleksandar Mihajlovic

[roesekoSICKAG]

Hello @Aleksandar-1
The working group is currently finalizing the release of the next version V2.0.0. We noticed during the work and extension process that there are discrepancy between the pdf and the yaml. Therefore it was decided to have the REST interface only described by the OpenAPI document (yaml) to avoid confusion and simplify the entry point for developers. The pdf file will contain some top level information and describe the general concept.

The problem you were facing should be resolved in this release which will be soon in the official review phase.
You can have a look at the develop branch.

[Aleksandar-1]

Hello @roesekoSICKAG
Ok, thanks.

Regards