Skip to content

Commit d7f3eb1

Browse files
vmxvmx
committed
Add exploration report about type convention
This report was originally issue ipld#71. Closes ipld#71.
1 parent 40635e4 commit d7f3eb1

1 file changed

Lines changed: 165 additions & 0 deletions

File tree

‎design/history/exploration-reports/2018.09-type-convention.md‎

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
This document was archived from https://github.com/ipld/specs/issues/71.
2+
3+
#71: IPLD Type Convention
4+
-------------------------
5+
Opened 2018-09-20T22:57:15Z by Stebalien
6+
7+
Motivation 1: I'd like to be able to look at an IPLD object and know, approximately, it's intended interpretation (without guessing or using context).
8+
9+
Motivation 2: I'd like to be able to define or extend a type system for *my* IPLD application without having it completely fail to interop with other IPLD type systems.
10+
11+
Motivation 3: I'd like to buy some time to figure out the perfect type system.
12+
13+
---
14+
15+
We've been discussing IPLD type *systems* but these discussions usually boil down to implementing the perfect system. I'd like to propose an alternative: the IPLD type convention.
16+
17+
Proposal: `@type: $something` denotes a type. What this type *means* depends on the type's type (if specified).
18+
19+
Why @? It's less likely to conflict but I'm not fixated on it.
20+
21+
Why "the IPLD type convention"? This isn't a specification. Basically, I'm giving in to JSON duck-typing and calling it "good enough".
22+
23+
Why is it good enough? This is a decentralized system so we'll have to check everything *anyways*. Trying to prescribe structure on users tends to lead to more trouble than it's worth (IMO). If we need more structure, we can always give the type a type to make sure we're operating within the correct type system.
24+
25+
How will this work with existing formats:
26+
27+
1. CBOR/JSON: Do nothing. For existing objects without a `@type`, these objects simply don't have types (within this system). Type systems that need to give everything *some* type can just give these some
28+
2. Git (tree, commit, etc), Eth, etc: I'd *like* to retroactively add in a type field. Thoughts? I kind of doubt this will break anything.
29+
30+
---
31+
32+
We've *also* talked about adding a new format with the structure `<CidOf(type)><data>`. That is, introduce a new format where we put all the type and schema information in a separate object, prepending the CID of this separate object to the *actual* object (the value).
33+
34+
After considering this for a bit, I've realized we should treat these as separate concerns: we're conflating *types* with *schemas*. There's no reason we can't introduce this new, compressed format at some later date even if we go with the above "type convention" proposal.
35+
36+
---
37+
38+
Disclaimer: this was *not* my idea, I've just finally convinced myself that it's probably "good enough".
39+
40+
Thoughts @jonnycrunch (you're the one who told me to look into the JSON-LD spec), @diasdavid, @davidad, @whyrusleeping?
41+
42+
---
43+
44+
While I'd like to avoid prescribing *too* much, I'd like to define a set of conventions that users *should* follow. For example:
45+
46+
* `@type: CID` - CID points to the actual type.
47+
* `@type: {}`: inline type. This will often be used for type "constructors". For example: `{@type: {@type: "generic", constructor: CidOfConstructor, parameters: [...]}`.
48+
* `@type: "string"`: A human readable string/path. IMO, this should *usually* be used to specify the type *system*.
49+
* `@type: 1234`: A multicodec. A reasonable type-of function would look this multicodec up in the multicodec table to map it to a CID.
50+
* `@type: [thing1, thing2, thing3]`: multiple types.
51+
52+
---
53+
#### (2018-11-12T19:05:30Z) jonnycrunch:
54+
@Stebalien Seems that you are most concerned with simple General Purpose data types definitions to start.
55+
56+
```
57+
"simpleTypes": {
58+
"enum": [
59+
"array",
60+
"boolean",
61+
"integer",
62+
"null",
63+
"number",
64+
"object",
65+
"string"
66+
]
67+
},
68+
69+
```
70+
71+
You could then build upon this and add support for more complex data types to give more meaning and context. This would help with validation of the structure.
72+
73+
An simple example extension would be `date` and `datetime`, which are an extension of `{ "@type" : "string"}` but the context would define the syntax of the string.
74+
75+
Presently, the handling of `datetime` in `@context` is `xsd:datetime` which references [http://www.w3.org/2001/XMLSchema#](http://www.w3.org/2001/XMLSchema#), where the explaination as `documentation source` is in [html](https://www.w3.org/TR/xmlschema-2/#dateTime).
76+
77+
My favorite annotation in this xml is:
78+
79+
>First the built-in primitive datatypes. These definitions are for information only, the real built-in definitions are *magic*.
80+
81+
Example for `string` from [XMLSchema](https://www.w3.org/2001/XMLSchema.xsd):
82+
83+
84+
<xs:simpleType name="string" id="string">
85+
<xs:annotation>
86+
<xs:appinfo>
87+
<hfp:hasFacet name="length"/>
88+
<hfp:hasFacet name="minLength"/>
89+
<hfp:hasFacet name="maxLength"/>
90+
<hfp:hasFacet name="pattern"/>
91+
<hfp:hasFacet name="enumeration"/>
92+
<hfp:hasFacet name="whiteSpace"/>
93+
<hfp:hasProperty name="ordered" value="false"/>
94+
<hfp:hasProperty name="bounded" value="false"/>
95+
<hfp:hasProperty name="cardinality" value="countably infinite"/>
96+
<hfp:hasProperty name="numeric" value="false"/>
97+
</xs:appinfo>
98+
<xs:documentation source="http://www.w3.org/TR/xmlschema-2/#string"/>
99+
</xs:annotation>
100+
101+
And more specfically for `datetime`:
102+
103+
<xs:simpleType name="dateTime" id="dateTime">
104+
<xs:annotation>
105+
<xs:appinfo>
106+
<hfp:hasFacet name="pattern"/>
107+
<hfp:hasFacet name="enumeration"/>
108+
<hfp:hasFacet name="whiteSpace"/>
109+
<hfp:hasFacet name="maxInclusive"/>
110+
<hfp:hasFacet name="maxExclusive"/>
111+
<hfp:hasFacet name="minInclusive"/>
112+
<hfp:hasFacet name="minExclusive"/>
113+
<hfp:hasProperty name="ordered" value="partial"/>
114+
<hfp:hasProperty name="bounded" value="false"/>
115+
<hfp:hasProperty name="cardinality" value="countably infinite"/>
116+
<hfp:hasProperty name="numeric" value="false"/>
117+
</xs:appinfo>
118+
<xs:documentation source="http://www.w3.org/TR/xmlschema-2/#dateTime"/>
119+
</xs:annotation>
120+
<xs:restriction base="xs:anySimpleType">
121+
<xs:whiteSpace value="collapse" fixed="true" id="dateTime.whiteSpace"/>
122+
</xs:restriction>
123+
</xs:simpleType>
124+
125+
126+
More complex data types would be generators and would help with the IPLD selectors issue.
127+
128+
129+
As far as JSON-LD, I'm rolling back my support of it. There is SO much reliance on location-based mappings. I have really started to look into how to strip out all reliance of the location and make it a pure content-addressed schema. But I'm getting a "symbol grounding problem". Also, there is so much self-referencing that my script fails given the cycles in the graph. I have moved away from the w3c model and looking at wikidata. Unfortunately, there isn't a good mapping for simple data types like `datetime` above. I think your "good enough" approach expresses the fundamental "intentionality" that point the user in the direction of the proper meaning. Wikidata's approach is to give many and and allow users to "triangulate" the meaning, especially across languages.
130+
131+
I, myself, like inline link `<cid>`:
132+
133+
```
134+
{
135+
...
136+
@type : { "/" : "<cid>" }
137+
}
138+
```
139+
140+
The use of `@type` to denote the object is an instance of a class of entities.
141+
142+
The problem is what do you link to? You'd be building a whole [ontology](http://ontodm.com/ontodt/OntoDT.owl) for data types.
143+
144+
BTW, there is an ISO standard for [General Purpose Datatypes](https://en.wikipedia.org/wiki/ISO/IEC_11404).
145+
146+
If you keep it simple and start with `strings`, and those strings are defined in the `@context`.
147+
148+
```
149+
{
150+
@context : { "/" : "<cid>" },
151+
...
152+
@type : "string"
153+
}
154+
```
155+
156+
More complicated examples can build out from here.
157+
158+
In theory, this syntx for links should be compatible with json-ld, but in practice it not. see my [issue #110 in JSON-ld](https://github.com/w3c-ccg/did-spec/pull/110#issuecomment-431356177).
159+
160+
---
161+
#### (2019-01-12T19:04:54Z) pavetok:
162+
> I'd like to be able to look at an IPLD object and know, approximately, it's intended interpretation (without guessing or using context).
163+
164+
Why does it necessary to embed type information into data itself?
165+
Modern CTT, for example, [says](https://www.youtube.com/watch?v=LE0SSLizYUI) that typing judgments are completely separate things. As consequence one value can inhabit multiple types.

0 commit comments

Comments
 (0)