Begin prototyping data types of fields and optional #173
Conversation
- I'm not 100% sure if we should link using ecmascript, or another standard for the data types. WhatWG has Infra https://infra.spec.whatwg.org/#string as an example, but then I didn't see Array. Still it would be nice to link and point to a standard, but that would be JSON, and I couldn't figure out how to make the ReSpec shortcut links work with RFC8259 and so resorted to the shortcut links using ecmascript (but this all could be changed I'm sure if we knew more or had a friend in ReSpec land)
✅ Deploy Preview for reconciliation-api-specs ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
There was a problem hiding this comment.
Formatting looks good, gives nice overview of data type & optional vs. required.
Made one inline suggestion. Also ReSpec complains about the unused required definition. I think omitting required looks good though, so maybe we can just remove the dfn and make it bold instead? Or link to it once from some place?
Co-authored-by: Fabian Steeg <[email protected]>
- Also remove duplicate phrasing paragraph for JSON convention used
Thanks!
Yeah, agree. So, instead, I now have just put a comment inside doc about that, and then made it only bold/italic to match. Finally, does anyone have opinions on the linking for the data types? Notice, if you hover or click on "String" or "Array" etc. that it's currently linked to "ecmascript". Is that OK you think? or should we link to some other standard available in xref ? |
|
I'll instead link the Data Types against the RFC8259 JSON Specification |
| <dt><code>description</code></dt> | ||
| <dd>{{String}} ({{optional}}) a <emph>description</emph> as a human-readable string;</dd> | ||
| <dt><code>type</code></dt> | ||
| <dd>{{Array}} ({{optional}}) list of <a>types</a>, possibly empty, the entity is classified by;</dd> |
There was a problem hiding this comment.
@fsteeg Does this appended phrase make things more clear, or does it assume too much? I felt like it was missing this context, which might not be apparent to developers outside of Semantic Web or Knowledge Graph circles (or just getting introduced to them) when we're talking about Entities and their Types.
|
|
Looks good to me in principle. Seeing the type directly makes it clearer. It feels a bit like there's a delimiter (e.g. a dot?) missing between the type and the description, but maybe it's fine. I think the description should be consistently capitalized though. |
|
@fsteeg Let's just take this as an example to come to consensus, and to ensure I understand what you are asking for:
|
|
Yes, that's what I meant. |
There was a problem hiding this comment.
I'm not super fond of redefining the JSON concepts. Intuitively we should be able to just link to whatever spec defines that and avoid making our spec even longer (I think it's already a bit scary because of its length).
Concerning the formatting of field types, it feels to me that we are missing a sort of delimiter between the field type and its description. An alternative way of formatting this would be to have the field name, type, optional status and description all gathered in a table.
Fixes #157