Skip to content

feat: Clarify "reference" properties spec #928

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
B13rg wants to merge 10 commits into
base: main
Choose a base branch
from
Open

feat: Clarify "reference" properties spec #928

Changes from 1 commit
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
51013cb
Clarify "reference" properties in various objects
B13rg Jul 31, 2025
d558607
Clarify wording
B13rg Jul 31, 2025
b0262d3
Clarify field reference errors
B13rg Aug 1, 2025
750acf9
Merge remote-tracking branch 'origin/main' into docs-1.1-ref
B13rg Aug 6, 2025
c7851fe
Clarify reference type
B13rg Aug 6, 2025
3ab62ef
Merge remote-tracking branch 'origin/main' into docs-2.1-ref
B13rg Aug 21, 2025
b432753
clarify fileobject terminology
B13rg Aug 21, 2025
8e9af3a
error, instead of warn
B13rg Aug 21, 2025
71fe5c3
Syntax
B13rg Oct 30, 2025
c474f4b
Update terminology to clarify metadata schema and structure
B13rg Oct 30, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 14 additions & 14 deletions docs/croissant-spec-draft.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -719,7 +719,7 @@ A `FileSet` is a set of files located in a container, which can be an archive `F
</thead>
<tr>
<td>containedIn</td>
<td>Reference</td>
<td>FileObject or FileSet <code>@id</code></td>
<td>MANY</td>
<td>The source of data for the <code>FileSet</code>, e.g., an archive. If multiple values are provided for <code>containedIn</code>, then the union of their contents is taken (e.g., this can be used to combine files from multiple archives).</td>
</tr>
Expand Down Expand Up @@ -917,21 +917,21 @@ A `Field` is part of a `RecordSet`. It may represent a column of a table, or a n
</tr>
<tr>
<td>references</td>
<td>Reference</td>
<td>Field <code>@id</code></td>
<td>MANY</td>
<td>Another <code>Field</code> of another <code>RecordSet</code> that this field references. This is the equivalent of a foreign key reference in a relational database.</td>
<td>An unordered list of references to other <code>RecordSet</code> <code>Field</code>s. This is the equivalent of a foreign key reference in a relational database.</td>
</tr>
<tr>
<td>subField</td>
<td>Field</td>
<td>Field <code>@id</code></td>
<td>MANY</td>
<td>Another <code>Field</code> that is nested inside this one.</td>
<td>An unordered list of references to <code>Field</code>s that are nested within this one.</td>
</tr>
<tr>
<td>parentField</td>
<td>Reference</td>
<td>Field <code>@id</code></td>
<td>MANY</td>
<td>A special case of <code>SubField</code> that should be hidden because it references a <code>Field</code> that already appears in the <code>RecordSet</code>.</td>
<td>An unordered list of references to <code>Field</code>s. A special case of <code>SubField</code> that should be hidden because it references a <code>Field</code> that already appears in the <code>RecordSet</code>.</td>
</tr>
<tr>
<td>annotation</td>
Expand Down Expand Up @@ -1026,21 +1026,21 @@ The ratings `RecordSet` above corresponds to a CSV table, declared elsewhere as
</thead>
<tr>
<td>fileObject</td>
<td>Reference</td>
<td>FileObject <code>@id</code></td>
<td>ONE</td>
<td>The name of the referenced <code>FileObject</code> source of the data.</td>
<td>The id of the <code>FileObject</code> source of the data.</td>
</tr>
<tr>
<td>fileSet</td>
<td>Reference</td>
<td>FileSet <code>@id</code></td>
<td>ONE</td>
<td>The name of the referenced <code>FileSet</code> source of the data.</td>
<td>The id of the <code>FileSet</code> source of the data.</td>
</tr>
<tr>
<td>recordSet</td>
<td>Reference</td>
<td>RecordSet <code>@id</code></td>
<td>ONE</td>
<td>The name of the referenced <code>RecordSet</code> source.</td>
<td>The id of the referenced <code>RecordSet</code> source.</td>
</tr>
<tr>
<td>extract</td>
Expand Down Expand Up @@ -1371,7 +1371,7 @@ If the example values cannot easily be provided directly within the Croissant de

### Joins

Croissant provides a simple mechanism to create a "foreign key" reference between fields of recordsets. The property `references` of `RecordSet` means that values in the `Field` that contains the reference are taken from the values of the target `Field`. The target is generally the key of the target `RecordSet`.
Croissant provides a simple mechanism to create a "foreign key" reference between fields of RecordSets. The property `references` of `RecordSet` means that values in the `Field` that contains the reference are taken from the values of the target `Field`. The target is generally the key of the target `RecordSet`.

For example, the `ratings` `RecordSet` below has a `movie_id` field that references the `movies` `RecordSet`.

Expand Down