Begin prototyping data types of fields and optional

thadguidry commented 2 months ago

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] commented 2 months ago

Deploy Preview for reconciliation-api-specs ready!

Name	Link
Latest commit	7ed08690def93656ca217b37e53555b9b8f9edff
Latest deploy log	https://app.netlify.com/sites/reconciliation-api-specs/deploys/661de3241be65f00084cf1a3
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.

thadguidry commented 2 months ago

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 commented 3 weeks ago

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

reconciliation-api / specs