#1339 split OPCUA document into Extensions & Adapters doc

[thompson-tomo]

Fixes #1339

Proposed Changes

• Splits the OPCUA document in 2

Release Note

This change splits the OPCUA into 2 distinct documents, with 1 describing the extensions necessary for the messages to be mapped to cloud events and the other document being an adapter document describing how the OPCUA message properties are to be mapped to either the core cloud event message or to generic extensions.

[duglin]

@koepalex any thoughts on this?

I don't think this PR changes anything semantically, just organizationally. So, the questions that come to mind for me is:
is it better for users to have this split or would it be better to have all of OPCUA in one doc? Even if it does (sort of) live in both worlds?

I'm leaning towards "1 doc is a better user experience". But I also wonder if this split between adapters and extensions is something we should have at all? Conceptually they are different things, one adds new attributes and one says how to leverage existing attributes, but (as this situation is pointing out) there may be situations where we do both. And I'm not keen on creating 2 docs each time this situation comes up just for the sake of "documentation purity".

So, to me the choices come down to:
1 - leave it as is, and take the position that if something defines a new attribute it's an "extension", even if also defines a mapping for CE or other extension attributes
2 - force each case that does both to create 2 docs
3 - find a generic name (e.g. domains, mappings) for a new dir and then move all of them into that one dir. It's not a huge list anyway. Or a combo name "extensions-adapters". Not quite as obvious as the current naming though.

If I had to pick one... my current thinking is option 1. Let's discuss on tomorrow's call.

[thompson-tomo]

For me I much prefer option 2 as the hope I would have is when adapters are being prepared and an extension is identified as being needed it is defined in a generic manner where appropriate to foster reusage. What I mean by this is why couldn't we define an extension dataversionand then in the adapter for OPCUA specify that the value of that attribute is opcuametadatamajorversion + "." + opcuametadataminorversion. This way anyone who wants to version the data value they can.

[duglin]

In this OPCUA case, do you see the OPCUA adapter being used w/o the extensions? Or visa-versa? I know the extension attributes are all tagged as OPTIONAL based on other bits of data, but if we assume that the criteria for their usage was actually met, do you still people seeing NOT using the extension attributes?

I'm wondering how often one doc will be used w/o the other - and if NOT using both isn't an edge case then a split seems more reasonable. But I don't have the background in OPCUA to know which is more likely.

[thompson-tomo]

I would hope it is rare that an adapter also needs extensions which are not reusable to other adapters.

[duglin]

I would hope it is rare that an adapter also needs extensions which are not reusable to other adapters.

@thompson-tomo I'm not clear on whether this answers my question, and now I have some more :-)

• Do you see the OPCUA adapter being used w/o the OPCUA extension attributes? The example in the adapter doc does show it. While I'm sure it's possible, what do you think the most common usage will be... to include them or not?
• Is it odd that the body of the OPCUA adapter talks about the core spec attributes and other extensions but not the OPCUA extensions, yet mentions them in the sample? Seems odd to be called "OPCUA adapter" but really only mention the OPCUA extensions in non-normative examples.

[thompson-tomo]

@duglin hopefully I have answered them this time.

Do you see the OPCUA adapter being used w/o the OPCUA extension attributes? The example in the adapter doc does show it. While I'm sure it's possible, what do you think the most common usage will be... to include them or not?

I would hope that the dataschema attribute is used in messages which means that the version extensions are not to be used. Perhaps they should be deprecated to encourage a unified/single approach.

Is it odd that the body of the OPCUA adapter talks about the core spec attributes and other extensions but not the OPCUA extensions, yet mentions them in the sample?

Changes have been made to improve this and to clear it up.

[koepalex]

For me the use case to use the adapter without the extension is not yet clear, therefore I lean towards option 1 (as @duglin). Specific in OPC UA where headers (DatasetMessageHeader) are defined and we can define the mapping, what is the value of separating those, purely editorial? (sorry If I miss the point here...)

[thompson-tomo]

I am very much a believer of consistency which in this case would be having all extensions defined in the same folder & structure.

As per the adapter document, an extension is only needed in the event that the dataschema attribute is not used. I would argue that for OPC UA we should always be using that attribute hence the version extensions are not needed to be used.

By the same measure I feel that as part of the request for a new extension it should be checked if a generic naming could be used. Hence making OPC UA a rare case of needing multiple docs.

[duglin]

As per the adapter document, an extension is only needed in the event that the dataschema attribute is not used. I would argue that for OPC UA we should always be using that attribute hence the version extensions are not needed to be used.

Are you suggesting that the OPCUA extensions are not needed, ever ?

[thompson-tomo]

@duglin as per the current documentation the only required extension would be opcuastatus as the other 2 have the below constraint

OPTIONAL but MUST NOT be present if dataschema is used

If for OPCUA we state dataschema is required the version extensions would never be used. For the status I would see this as a candidate for a generic extension.

[thompson-tomo]

re-opened as #1347 it got closed by mistake when fixing clo.