Make reference to JSO informative by explaining the data qualities #37

cabo · 2021-10-22T20:23:13Z

No description provided.

akeranen

I think this change makes sense. A set of small change suggestions inline.

sdf.md

akeranen · 2021-10-23T19:49:32Z

sdf.md

+constrains the data value to be an integer multiple of the number
+given.
+(Type "`integer`" can also be expressed as a "`multipleOf`" quality of
+value 1, unless another "`multipleOf`" quality is present.


This might confuse more than clarify. I would probably leave this sentence out.

And missing closing ")".

I find that piece of information useful; it makes the reader think, which is often a prerequisite to understanding.

akeranen · 2021-10-23T19:49:32Z

sdf.md

+The length (as measured in characters) can be constrained by the
+additional data qualities "`minLength`" and "`maxLength`", which are
+inclusive bounds.
+Note that the previous version of the present document explained


Instead of talking about the mistake in the previous version, I'd suggest to say here just something along the lines of:

Note that the length of the string in characters is not necessarily the same as in octets unless specific encoding that has this feature (e.g., UTF-8) is used.

Er, UTF-8 does not have the same number of bytes as it encodes characters.

akeranen · 2021-10-23T19:49:32Z

sdf.md

+The data quality "`pattern`" takes a string value that is interpreted
+as an [ECMA-262] regular expression in Unicode mode that constrain the
+string (note that these are not anchored by default, so unless `^` and
+`$` anchors are employed they match any string that *contains* a match


It wasn't obvious from first read where "they" refers to, so I was thinking of suggesting here "the expressions", but not sure if that's actually much better.

akeranen · 2021-10-23T19:49:32Z

sdf.md

+describe entries in the specified JSON object: The key gives an
+allowable map key for the specified JSON object, and the value is a
+map with a named set of data qualities giving the type for the
+corresponding value in the specified JSON object.


Here we might need an example

... which are all over the document, no?

sdf.md

akeranen · 2021-10-23T19:49:32Z

sdf.md

-| required         | array of strings                                                 | (object) names of properties (note 2) that are required in the JSON map ("object") |
-| properties       | named set of data qualities                                      | (object) entries allowed for the JSON map ("object")                  |
-{: #sdfdataqual1 title="Qualities of sdfProperty and sdfData borrowed from json-schema.org"}
-
 (1) A type value of `integer` means that only integral values of JSON


Given the table is removed, I guess so should be the notes?

akeranen · 2021-10-23T19:49:32Z

sdf.md

 (1) A type value of `integer` means that only integral values of JSON
 numbers can be used.

-(2) Note that the term "properties" as used for map entries in {{-jso}} is unrelated to sdfProperty.
+(2) Note that the term "properties" as used for map entries in JSO is unrelated to sdfProperty.


(same as above)

akeranen · 2021-10-23T19:49:32Z

sdf.md

@@ -823,32 +838,10 @@ homogeneous arrays of numbers, text, Booleans, or maps.  (This list might be
 extended in a future version of SDF.)  An "allowed value" is a value


I think this parts needs update based on the removed table below (e.g., "allowed types" not used anymore).

The CDDL, where this term continues to be used, should be self-explanatory (as well as more precise) here, so I have removed this as well.

Co-authored-by: Ari Keränen <ari.keranen@gmail.com>

WAvdBeek · 2021-10-25T09:25:09Z

sdf.md

@@ -83,6 +85,14 @@ informative:
 # VERSION 2.1.2 | April 2020


v2.1.4 August 2021

WAvdBeek · 2021-10-25T09:26:19Z

Hi Carsten,
just for my understanding, this is describing json inside of this doc instead of referencing it correct?
no obvious issues with that, if that helps the progress in IETF.

cabo · 2021-10-25T09:44:48Z

JSON is defined in RFC 8259 (STD 90), but this indeed pulls in definitions of the keywords that we have borrowed from the json-schema.org proposals. Note that OCF is based on Swagger 2.0 which appears to be based on "draft-4" (draft‑wright‑json‑schema‑00 actually, which is draft-5, which is draft-4 pretty much anyway), so exclusiveM..imum has a different meaning there, but apart from that change (which we have agreed a while ago) JSO keywords from OCF swagger should simply continue to just drop into SDF.

WAvdBeek · 2021-10-25T10:24:12Z

sdf.md

+JSO-based keywords are also used in the specification techniques of a
+number of ecosystems, but some adjustments may be required.
+
+E.g., {{OCF}} is based on Swagger 2.0 which appears to be based on


I am fine with having implementation notes.

not sure if we have to call out the exclusive/min/max thought since the conversion already handles this.

It is mostly a template for the paragraphs that we may need to write for other ecosystems.
(And, I think, it is good to know that there are minor tweaks, even if they already are implemented.)

cabo added 2 commits Oct 22, 2021

Make reference to JSO informative, explain what has been borrowed.

3f40976

Regenerate

4f61f1c

cabo requested review from akeranen and mjkoster Oct 22, 2021

akeranen suggested changes Oct 23, 2021

View changes

cabo and others added 5 commits Oct 23, 2021

Update sdf.md

c772f85

Co-authored-by: Ari Keränen <ari.keranen@gmail.com>

Update sdf.md

2a84473

Co-authored-by: Ari Keränen <ari.keranen@gmail.com>

Update sdf.md

03dcd2e

Co-authored-by: Ari Keränen <ari.keranen@gmail.com>

Changes based on Ari's input

5613e54

Regenerate

9d4c86a

WAvdBeek approved these changes Oct 25, 2021

View changes

sdf.md Outdated

@@ -83,6 +85,14 @@ informative:

# VERSION 2.1.2 | April 2020

Copy link

Contributor

WAvdBeek Oct 25, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

v2.1.4 August 2021

Update comment about OCF spec ref

6b3d61a

Add Implementation Note for JSO-inspired vs. OCF/Swagger 2.0.

972713d

WAvdBeek reviewed Oct 25, 2021

View changes

mjkoster approved these changes Oct 25, 2021

View changes

cabo merged commit 3d1402d into master Oct 25, 2021

ietf-wg-asdf / SDF Public

Make reference to JSO informative by explaining the data qualities #37

Make reference to JSO informative by explaining the data qualities #37

cabo commented Oct 22, 2021

akeranen left a comment

akeranen Oct 23, 2021

cabo Oct 23, 2021

akeranen Oct 23, 2021

cabo Oct 23, 2021

akeranen Oct 23, 2021

akeranen Oct 23, 2021

cabo Oct 23, 2021

akeranen Oct 23, 2021

cabo Oct 23, 2021

akeranen Oct 23, 2021

cabo Oct 23, 2021

akeranen Oct 23, 2021

cabo Oct 23, 2021

WAvdBeek Oct 25, 2021

WAvdBeek commented Oct 25, 2021

cabo commented Oct 25, 2021

WAvdBeek Oct 25, 2021

cabo Oct 25, 2021

		@@ -823,32 +838,10 @@ homogeneous arrays of numbers, text, Booleans, or maps. (This list might be
		extended in a future version of SDF.) An "allowed value" is a value

ietf-wg-asdf / SDF Public

Make reference to JSO informative by explaining the data qualities #37

Make reference to JSO informative by explaining the data qualities #37

Conversation

cabo commented Oct 22, 2021

akeranen left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

WAvdBeek commented Oct 25, 2021

cabo commented Oct 25, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment