Pair Credential with their Supporting documents

[BenjaminMoe]

Related to #352. Reference images for documents have been included in descriptions.json file. This is a stop-gap for re-organizing the documentation. The reference images for specific document should be moved to their respective yml files in a future PR.

[nissimsan]

@BenjaminMoe , great that you've moved this conversation to a dedicated issue.

@OR13 , ref the discussion on the initial PR, I understand that we can add pictures on the .yml files. But I don't think we should.

[OR13]

@nissimsan do you agree to abide by OAS 3 and treat descriptions as markdown? or are you saying we should profile down from OAS 3 and forbid markdown in descriptions?

[nissimsan]

@OR13, I would love support for markdown OAS!

But it's a different point I am trying to make. @BenjaminMoe has externalized references to pictures like the one below into a separate file. And I think that's correct; while useful to display such legacy pictures on our main page, I wouldn't want to include them as part of the formal schema.

[TallTed]

The formal schema could include "based on" or "derived from" or "influenced by" or similar links to the scanned paper forms. I wouldn't include the actual images in the formal schema.

[OR13]

https://swagger.io/specification/

Throughout the specification description fields are noted as supporting CommonMark markdown formatting. Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by CommonMark 0.27. Tooling MAY choose to ignore some CommonMark features to address security concerns.

[nissimsan]

I wouldn't include the actual images in the formal schema.

+1

[BenjaminMoe]

Changed the title as my updated PR document use the same json work around, in favor of moving supporting docs to their own section. https://github.com/w3c-ccg/traceability-vocab/pull/364/files

[BenjaminMoe]

Use openAPI 3.0 specification for markdown fields.

[OR13]

I am a +1 for using absolute URLs and markdown.

[BenjaminMoe]

Needed improvement.

[mkhraisha]

@BenjaminMoe any updates on this?