Provide documentation for _metadata feature

[thjaeckle]

Was not done as part of #680, so must still be done.

[JulianFeinauer]

@thjaeckle and @jufickel-b I started to work on the documentation in this branch: https://github.com/JulianFeinauer/ditto/tree/feature/785-documentation-metadata do you agree with the current setup?

[thjaeckle]

@JulianFeinauer cool - I just had a brief look.

• adding it as a new page is good - as it is a new concept
• then you also must add it to the _data/sidebards/ditto_sidebar.yml or else it won't show in the navigation
• the current implementation does not have any predefined metadata, even not issuedAt - so that one also is not implicitly set
  • I created Implicit metadata creation on JSON leaves #778 in order to bring modified and revision as predefined (and Ditto managed) metadata

I'm not sure if that will work:

{
  "key":"*/",
  "value":{"issuedAt": someTimestamp }
}

I would have expected to look like:

{
  "key": "*/issuedAt",
  "value": someTimestamp
}

[JulianFeinauer]

Hey @thjaeckle thanks for the feedback.. I did not finish it the weekent because I wanted to sit down and try it out myself as I did not track all changes you and @jufickel-b did in the code so before submitting it as PR I will try to test it.

[jufickel-b]

@thjaeckle your expectation is correct.
@JulianFeinauer you can have a look at the unit tests to see the format of metadata headers: DefaultMetadataHeaderTest

[w4tsn]

This not only needs to be added to the doc pages but also to the swagger docs.

@jufickel-b so I suppose that all complex json objects have to be broken down such that I get one array entry for each leaf. E.g. the issuedBy example from the docs proposal would have to be split up into two entries, correct?

[w4tsn]

The API example / specification under basic-thing.md needs to be updated to.

In the current docs: https://www.eclipse.org/ditto/basic-thing.html

[thjaeckle]

Closed via merged #806