search

w3c / yml2vocab

Generate RDFS vocabulary files from YAML
https://w3c.github.io/yml2vocab
Other
14 stars 5 forks source link

Using HTML for description formatting #9

Closed iherman closed 1 year ago

iherman commented 1 year ago

This PR is to fix #8 ie, indirectly, answer to the request, in https://github.com/w3c/vc-data-integrity/pull/79#discussion_r1086212067, of @TallTed

The approach chosen is to consider the full "comment" field in the vocabulary's YML description as an HTML fragment, rather than a pure text with some ad-hoc microsyntax. That requires a slight update on some vocabulary entries (most of them are just a simple textual paragraph, that simply translates into a <div>, which is fine), but not much. Nevertheless, it will require (if/when this version of yml2vocab is merged and deployed on npm) a slight technical update on the security vocabulary. Nothing major.

The result, ie, the "new" look of the vocabulary can be previewed separately, more exactly the entry on publicKeyMultibase. Everything else is visually unchanged, all changes are under the hood. Reviewers should not worry about the content of those files, the only thing that matters is how that file "looks", ie, what the effects of the TypeScript code updates are.

The changes are also visible in the turtle and json-ld files, insofar as the comment fields are now typed literals using the rdf:HTML datatype. This is exactly why that datatype was created in RDF 1.1 after all... (Again, do not worry about the exact content of the vocabulary files, just consider the effect on the changes for the comment fields.)

iherman commented 1 year ago

@TallTed it took a bit longer to get to this, but I had other priorities...

iherman commented 1 year ago

@msporny, do you see any reason why this should not be merged? I would like to go ahead with some code cleanup (without any feature change), but I want to do this on the merged version rather than the original one...

(Just out of interest: the cleanup idea came up because I looked at what it would mean to turn this into a deno project rather than TS+Node.js, and deno is stricter in terms of TypeScript. And no, there is no other reason than technical interest...)

iherman commented 1 year ago

There are a variety of other items that were changed in credentials.yml that made me pause and go "hmm, that makes me nervous'", but not enough to say this shouldn't be merged... since this repo isn't the "official" version of that vocabulary.

Exactly...

I will, actually, issue a PR on the official version of the vocabulary soon in which I will only do formatting changes. I think any content change (and we still have the issue pending on cleaning up that vocabulary!) should be done on yet another PR. To come...