refactor(schemas): house cleaning #9
Conversation
add `examples` to common components update schema uri identifiers (`$id`) relax constraints in decimal schema for reuse in money schema Update markdown descriptions to align vocabulary with JSON Schema [https://aep.dev/213] #134
There was a problem hiding this comment.
thanks for the contribution!
A couple places I'd like to check on with respect to json schema correctness. One question about the usage of the term field vs properties that I wanted to check in with @rofrankel about.
| @@ -8,28 +8,28 @@ point representation in order to avoid precision errors. | |||
| A `Decimal` represents a decimal number in a form similar to scientific | |||
| notation. | |||
|
|
|||
| It has two fields: | |||
| It has two properties: | |||
There was a problem hiding this comment.
I believe the reason these were described as "field" is because that's what protobuf calls them.
I think we had a discussion no what we would call the protocol-agnostic conflict, and landed on "fields" to match the existing AEP text. @rofrankel can correct me though.
There was a problem hiding this comment.
I don't remember the discussion, but at a first take that conclusion sounds good to my protobuf-biased self.
Aside from protobuf using one term and OAS using the other, is there an agnostic argument either way?
There was a problem hiding this comment.
To be clear, the properties term is not OAS specific but rather JSON Schema derived. Here's a nice long summary from SO. IMO, because we discussing a schema definition, I would prefer the use of properties but I'm open to discussion on it.
https://stackoverflow.com/questions/295104/what-is-the-difference-between-a-field-and-a-property
There was a problem hiding this comment.
That's a fair clarification...though from the perspective of trying to be agnostic to protobuf vs. OAS, OAS and JSON Schema are effectively the same entity (they're always and only used together with respect to protobuf being an alternative).
single quotes for mapping keys Co-authored-by: Yusuke Tsutsumi <[email protected]>
update reference Co-authored-by: Yusuke Tsutsumi <[email protected]>
There was a problem hiding this comment.
Sorry for the delay in following up on this. It LGTM other than the properties vs. fields question. I don't necessarily have a strong opinion on this (yet), but if we switch from the protobuf terminology to the OAS terminology without an objective/agnostic reason for doing so, I'm not sure it's an improvement.
couple issues in the existing json schema components that I cleaned up for JSON Schema tooling and validation
Also added the
phone_numberjson schema that was missing. I'm not sure if the interpretation of the text is correct, specifically for theshort_code. Please clarify if it's not correct.related:
PhoneNumbertype based ongoogle.type.PhoneNumber. #3