Handle unset optional properties #47

ctoher · 2018-07-12T19:05:11Z

Dear all,

I've inserted a first draft of the section on how to handle unset optional properties (i.e. properties with "null" values - #17 on the list of issues), as per the discussion during the meeting in Lausanne.

I've added this as a new subsection 3.3.4, but let me know if you think some of the information would be better suited in a different section, e.g. if the " IS KNOWN" filter option should be in the filter section instead. Please let me know if you have any other comments, questions or suggestions on this topic.

Best regards

Cormac.

rartino

This is based on the OPTIMaDe meeting discussion. This looks very good. We have a few changes suggested to formalize SHOULD and MUST in a few places. And there is one pagragraph about multi-valued properties that we did not quite understand, where we suggest a replacement.

And, also, there is an checked in .DS_Store file that should be removed from the pull request.

rartino · 2018-12-19T09:28:57Z

optimade.md

+
+Note that this only applies to properties that are described by a single value,
+and not to properties with multiple attributes such as the structure.
+In this case, attributes that have null value are simply omitted from the returned structure.


In an OPTIMaDe meeting discussion, we note that we have some trouble understanding exactly what this means. What we think is needed is to say that the text in this section only describes how the api handles properties that themselves are null, and does not regulate which values inside the data structure used by a properties can be null. That is rather to be described in relation to the definition of those data structures.

So:

Suggested change

In this case, attributes that have null value are simply omitted from the returned structure.

The text in this section describes how the api handles properties that are null. It does not regulate the handling of values inside property data structures that can be null. That use of null values is described in relation to the definition of those data structures.

(Note: I cannot get github to make a suggestion over several lines, but this is meant to replace the whole paragraph.)

rartino · 2018-12-19T09:31:46Z

optimade.md

+Unset optional properties in a database are properties that exist and have a specific value within a database for some materials entries,
+but are undefined for other entries, i.e. have the value 'null' within a JSON file or SQL database.
+
+Unset properties are not returned in the response unless explicitly requested in the search query.


Suggested change

Unset properties are not returned in the response unless explicitly requested in the search query.

Unset properties MUST NOT be returned in the response unless explicitly requested in the search query.

rartino · 2018-12-19T09:32:35Z

optimade.md

+but are undefined for other entries, i.e. have the value 'null' within a JSON file or SQL database.
+
+Unset properties are not returned in the response unless explicitly requested in the search query.
+Any comparisons involving unset properties should return a value of false,


Suggested change

Any comparisons involving unset properties should return a value of false,

Any comparisons involving unset properties MUST be evaluated as false,

rartino · 2018-12-19T09:36:53Z

optimade.md

+
+If a property is explicitly requested in a search query without value range filters,
+then all entries otherwise satisfying the query should be returned, including those with null values for this property.
+The value of these properties should be set to the JSON 'null' value in the response.


Suggested change

The value of these properties should be set to the JSON 'null' value in the response.

These properties MUST be set to the JSON 'null' value in the response.

rartino · 2018-12-19T09:38:41Z

optimade.md

+i.e. by definition the value of 'null' is outside of any defined search range.
+
+If a property is explicitly requested in a search query without value range filters,
+then all entries otherwise satisfying the query should be returned, including those with null values for this property.


Suggested change

then all entries otherwise satisfying the query should be returned, including those with null values for this property.

then all entries otherwise satisfying the query SHOULD be returned, including those with null values for this property.

ctoher · 2019-02-22T20:13:18Z

Dear all,

I've updated the draft of the section on how to handle unset optional properties (i.e. properties with "null" values - #17 on the list of issues), to incorporate Rickard's suggested changes.

I've slightly modified his suggestion for the last sentence of the paragraph about null values inside property data structures to try to make it clearer - let me know if this makes sense, or if you think something else would work better.

Best regards

Cormac.

giovannipizzi · 2019-04-24T13:18:45Z

After discussion in the skype call, what is missing in this PR is an update of the grammar. This can be done at the same time (or right after having discussed) issue #58

, Materials-Consortia#42, Materials-Consortia#19, Materials-Consortia#16, Materials-Consortia#47

ctoher · 2019-06-12T16:10:02Z

Dear all,

I've updated the specification for the handling of "null" properties. In particular, I updated the "IS KNOWN" and "IS UNKNOWN" discussion, including a cross-reference to section 5.2 (the filter specification where IS KNOWN and IS UNKNOWN are described). Please let me know if you have any comments or suggestions.

Best regards

Cormac.

giovannipizzi · 2019-06-12T21:13:32Z

optimade.md

@@ -377,6 +378,30 @@ the next course of action SHOULD be to fetch the resource objects under the
 to the corresponding database ID that was originally queried, using the object's
 `base_url` value.

+### <a name="h.3.3.4">3.3.4. Unset optional properties</a>
+
+Unset optional properties in a database are properties that exist and have a specific value within a database for some materials entries, but are undefined for other entries, i.e. have the value 'null' within a JSON file or SQL database.


To be consistent, I would always write null or 'null' as null instead, with backticks - both here and in a number of places below.

giovannipizzi · 2019-06-12T21:15:56Z

optimade.md

@@ -377,6 +378,30 @@ the next course of action SHOULD be to fetch the resource objects under the
 to the corresponding database ID that was originally queried, using the object's
 `base_url` value.

+### <a name="h.3.3.4">3.3.4. Unset optional properties</a>
+
+Unset optional properties in a database are properties that exist and have a specific value within a database for some materials entries, but are undefined for other entries, i.e. have the value 'null' within a JSON file or SQL database.


I don't know if we want to mention SQL here. Maybe just say "i.e. have the value null or are missing in the data source (that can be a JSON file, a database, ...)" or something like this? (assuming I'm understanding what you want to say here)

giovannipizzi · 2019-06-12T21:16:12Z

optimade.md

+
+Unset properties MUST NOT be returned in the response, unless explicitly requested in the search query. 
+
+Any comparisons involving unset properties MUST be evaluated as false,


Also here, I would use false instead of false?

ctoher · 2019-06-13T07:10:28Z

I fixed the null and false formatting as per Giovanni's comment. Let me know if there are any other formatting changes that should be made.

I removed the mention of SQL; this part now reads: "e.g. have the value null within a JSON file." The idea behind this part is just to give a concrete example of the types of values we're talking about; let me know if you think we should write this in a different way.

rartino

Approved

ctoher added 5 commits July 6, 2018 16:27

Unset properties specification

21463dc

Unset properties specification

7022a3d

Unset properties specification

490c360

Unset properties specification

85af4be

Unset properties specification

7ec7cd2

rartino reviewed Dec 19, 2018

View reviewed changes

ctoher added 2 commits February 22, 2019 10:18

Update optimade.md

36a6cd7

Update optimade.md

741ea9f

rartino added a commit to rartino/OPTIMADE that referenced this pull request May 12, 2019

Filter changes related to Materials-Consortia#58, Materials-Consortia#17

2b048c8

, Materials-Consortia#42, Materials-Consortia#19, Materials-Consortia#16, Materials-Consortia#47

rartino mentioned this pull request May 13, 2019

Updates to filtering language #69

Merged

ctoher added 4 commits June 12, 2019 14:24

Merge branch 'develop' into develop

a674a50

Update optimade.md

fee6256

Update optimade.md

3725759

Update optimade.md

2558802

ctoher added 3 commits June 12, 2019 17:19

Update optimade.md

31c17d2

Merge branch 'develop' into develop

09aceea

Update optimade.md

03a56c9

giovannipizzi requested changes Jun 12, 2019

View reviewed changes

Update optimade.md

2b0749c

ctoher requested a review from giovannipizzi June 13, 2019 07:47

ltalirz added the PR/ready-for-review Add this flag if you are the author of the PR and you want it to be reviewed. Remove it when editing label Jun 13, 2019

giovannipizzi approved these changes Jun 13, 2019

View reviewed changes

rartino approved these changes Jun 13, 2019

View reviewed changes

rartino merged commit fc5a1b1 into Materials-Consortia:develop Jun 13, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Handle unset optional properties #47

Handle unset optional properties #47

ctoher commented Jul 12, 2018

rartino left a comment •

edited

Loading

rartino Dec 19, 2018

rartino Dec 19, 2018

rartino Dec 19, 2018

rartino Dec 19, 2018

rartino Dec 19, 2018

ctoher commented Feb 22, 2019

giovannipizzi commented Apr 24, 2019

ctoher commented Jun 12, 2019

giovannipizzi Jun 12, 2019

giovannipizzi Jun 12, 2019

giovannipizzi Jun 12, 2019

ctoher commented Jun 13, 2019

rartino left a comment

	In this case, attributes that have null value are simply omitted from the returned structure.
	The text in this section describes how the api handles properties that are null. It does not regulate the handling of values inside property data structures that can be null. That use of null values is described in relation to the definition of those data structures.

	Unset properties are not returned in the response unless explicitly requested in the search query.
	Unset properties MUST NOT be returned in the response unless explicitly requested in the search query.

	Any comparisons involving unset properties should return a value of false,
	Any comparisons involving unset properties MUST be evaluated as false,

	The value of these properties should be set to the JSON 'null' value in the response.
	These properties MUST be set to the JSON 'null' value in the response.

	then all entries otherwise satisfying the query should be returned, including those with null values for this property.
	then all entries otherwise satisfying the query SHOULD be returned, including those with null values for this property.

Handle unset optional properties #47

Handle unset optional properties #47

Conversation

ctoher commented Jul 12, 2018

rartino left a comment • edited Loading

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

ctoher commented Feb 22, 2019

giovannipizzi commented Apr 24, 2019

ctoher commented Jun 12, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ctoher commented Jun 13, 2019

rartino left a comment

Choose a reason for hiding this comment

rartino left a comment •

edited

Loading