Pair Credential with their Supporting documents

w3c-ccg / traceability-vocab

A traceability vocabulary for describing relevant Verifiable Credentials and their contents.

https://w3id.org/traceability

Other

34 stars 35 forks source link

Pair Credential with their Supporting documents #357

Open BenjaminMoe opened 2 years ago

BenjaminMoe commented 2 years ago

Related to https://github.com/w3c-ccg/traceability-vocab/pull/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 commented 2 years ago

@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 commented 2 years ago

@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 commented 2 years ago

@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 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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

BenjaminMoe commented 2 years ago

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 commented 2 years ago

Use openAPI 3.0 specification for markdown fields.

OR13 commented 2 years ago

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

BenjaminMoe commented 1 year ago

Needed improvement.

mkhraisha commented 1 year ago

@BenjaminMoe any updates on this?