[Refactor pending] Align default types for entities and attributes with Schema.org

[fgalan]

As in other parts of the NGSIv2 API (e.g. DateTime), it has been proposed that instead of using string "none" as default type for entities and attributes at creation/update time a default aligned with Schema.org would be used.

In particular:

1. Regarding entities, the string "Thing" would be used (aligned with https://schema.org/Thing).
2. Regarding attributes, the type would depend on value JSON datatype, in paticular:
   • arrays is not clear (no suitable type under https://schema.org/DataType)
   • object is not clear (no suitable type under https://schema.org/DataType)
   • strings would use "Text" (aligned with https://schema.org/Text)
   • numbers would use "Number" (aligned with https://schema.org/Number)
   • bool would use would use "Boolean" (aligned with https://schema.org/Boolean)
   • null is not clear (no suitable type under https://schema.org/DataType)

Just to remark that the above rules would apply only to entities and attribute without explicity NGSI type declaration. In other words, if the user specifis NGSI type explicitely, that one will be used.

[fgalan]

Bullet 2 also applies to default metadata types.

[jmcanterafonseca]

we could have

array --> Array object --> https://schema.org/StructuredValue

null --> could it be type: null

thanks

[fgalan]

Maybe "StructuredValue" should be also used for arrays. Taking into account "StructureValue" definition:

Structured values are used when the value of a property has a more complex structure than simply being a textual value or a reference to another thing.

array can be considered a case of "a more complex structure than simply being a textual value or a reference to another thing".

(Note that in Orion terms, we already -since time ago- use to refer to both (objects & arrays) as "compund values" or "structures values")

[fgalan]

Regarding type "null" when the value is null, maybe we should use "Null" to align with all the other case, which use first letter capitalized.

Another alternative could be "None".

[fgalan]

Changes in NGSIv2 WIP .apib implemented in PR https://github.com/telefonicaid/fiware-orion/pull/2335

[fgalan]

Remember to edit implementation notes at https://github.com/telefonicaid/fiware-orion/blob/develop/doc/manuals/user/ngsiv2_implementation_notes.md once this gets implemented. Remove this:

Currently, Orion uses the string none as default for entities/attributes/metadata at creation/update time. However, this may change in the future, as described in https://github.com/telefonicaid/fiware-orion/issues/2223.

[fgalan]

Completed at NGSIv2 spec. Changing milestone to 1.3.0 (version in which this is going to be implemented at Orion).

[fgalan]

After merging PR https://github.com/telefonicaid/fiware-orion/pull/2469, some minor leftovers needs to be fixed to close this issue:

1. Modifications on https://github.com/telefonicaid/fiware-orion/blob/develop/doc/manuals/user/ngsiv2_implementation_notes.md (see above comments)
2. Recover the 1068_metadata_value_as_compound/metadata_value_as_compound_array.test.DISABLED test
3. Implement the FIXME P4 introduced in parseContextAttributeObject(). The existence of .test harness should "proctect" during the refactor work.

Items 1 and 2 should be completed before releasing 1.3.0. Item 3 could be refered to a next release.

[fgalan]

After merging PR https://github.com/telefonicaid/fiware-orion/pull/2478 only bullet 3 above is pending:

Implement the FIXME P4 introduced in parseContextAttributeObject(). The existence of .test harness should "proctect" during the refactor work.

[taliaga]

Hi guys, if I may just come in with a humble comment, I hope it's not too late.

I really like @jmcanterafonseca 's suggestion of using "Array" as default type for arrays. Or, if you want to keep it schema.org-like I think they call it itemList. Not only schema.org, but even JSON DataTypes make a distinction between array and object. The distinction is also embedded in the default types of many programming languages. And last but not least, Orion already identifies DEFAULT_ATTR_ARRAY_TYPE and DEFAULT_ATTR_OBJECT_TYPE, why mapping them back to the same string? 😄

That being said, my point is that, regardless of how you decide to name it, there is value in keeping the distinction of the two entity types. Solutions depending on data-types could this way leverage on the default typesystem orion uses without the need for them to explicitly send attribute types in their entities)

WDYT?

[fgalan]

Thank you for the feedback! However, note that changing current Orion implementation to use ItemList instead of StructuredValue for JSON arrays will break stable NGSIv2 RC-2016.10 (http://telefonicaid.github.io/fiware-orion/api/v2/stable/)

If value is an object or array, then StructuredValue is used.

Changing StructuredValue to ItemList for JSON arrays migth seem to be a slight adjustment but it could break existing client implementations relying in NGSIv2 RC-2016.10

[taliaga]

...will break stable NGSIv2 RC-2016.10

Oh, I see. Well, maybe something to consider for a next release.

Changing StructuredValue to ItemList for JSON arrays...

Yeap, definitively not worth also considering the consistency break that'd cause.

Ok, thanks anyway!

[fgalan]

Relabeling from APIv2 to APIv2-debt, to mean an issue that is part of the NGSIv2 specification but not yet implemented in Orion.

CC: @jmcanterafonseca