Begin prototyping data types of fields and optional

[thadguidry]

Fixes #157

• 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)
• Anyways, take a look at the Core Concepts section Entities where I begin to add them along with some extra info Terms Used and references we were missing about JSON standards in general that we talked about throughout the spec.

[netlify]

✅ Deploy Preview for reconciliation-api-specs ready!

Name	Link
🔨 Latest commit	a42b465
🔍 Latest deploy log	https://app.netlify.com/sites/reconciliation-api-specs/deploys/66e39cdce4a8a10007ffca31
😎 Deploy Preview	https://deploy-preview-173--reconciliation-api-specs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[fsteeg]

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?

[thadguidry]

Formatting looks good, gives nice overview of data type & optional vs. required.

Thanks!

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?

Yeah, agree. So, instead, I now have just put a comment inside doc about that, and then made it only bold/italic to match.
Also wrapped paratheses around them to showcase the syntax used in the document. I think this makes things easier to distinguish.

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 ?

[thadguidry]

I'll instead link the Data Types against the RFC8259 JSON Specification

[thadguidry]

@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.

[thadguidry]

@fsteeg

1. So I layered in the JSON spec conventions (and removed the ecmascript xref since we agreed to conform to just JSON spec), and then with those defined, I now began to add more datatypes. How do things look now (links look/feel good) (format is just fine)?
2. Also took the liberty to slightly clarify a few things and improve grammar. One thing I am wondering about is clarifying the Entities - type, where I appended ... the entity is classified by. Does that make good sense?

[fsteeg]

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.

[thadguidry]

@fsteeg Let's just take this as an example to come to consensus, and to ensure I understand what you are asking for:

<dd>{{Array}} ({{optional}}) list of <a>types</a>, possibly empty, the entity is classified by;</dd>

1. You want a dot between the datatype (or optional) and the description? Such as:
   <dd>{{Array}} ({{optional}}). List of <a>types</a>, possibly empty, the entity is classified by;</dd>
2. So you think descriptions should always start with a captial such as "list" should be "List" ?

[fsteeg]

Yes, that's what I meant.

[wetneb]

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.