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[bot]]

✅ Deploy Preview for reconciliation-api-specs ready!

Name	Link
🔨 Latest commit	0c80ce32a3c70f5dbd47afca0fbccf94aca4ee01
🔍 Latest deploy log	https://app.netlify.com/projects/reconciliation-api-specs/deploys/68c2b5011491400008c1292a
😎 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 project configuration.

[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

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]

Nice, I think it works to have String (optional) followed by the description of the field, it's quite natural.