Skip to content

Commit 7cfa826

Browse files
committed
defined and documented consumesData and producesData properties (codemeta/codemeta#188)
1 parent d75a803 commit 7cfa826

2 files changed

Lines changed: 96 additions & 2 deletions

File tree

‎README.md‎

Lines changed: 82 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -144,8 +144,8 @@ proposed extension as formulated
144144
[here](https://github.com/schemaorg/schemaorg/issues/1423), nothing in there is
145145
defined by us.
146146

147-
The link between `SoftwareSourceCode` and subclasses of `SoftwareApplication`,
148-
`WebAPI`, `WebPage` or `WebSite` is established using the `targetProduct`
147+
The link between `schema:SoftwareSourceCode` and subclasses of `schema:SoftwareApplication`,
148+
`schema:WebAPI`, `schema:WebPage` or `schema:WebSite` is established using the `schema:targetProduct`
149149
property. There is also a reverse property for this called
150150
``codemeta:hasSourceCode`` (see discussion
151151
[here](https://github.com/codemeta/codemeta/pull/229)).
@@ -160,6 +160,86 @@ be interpreted as the name of the executable within a certain undefined
160160
run-time context (e.g. an executable filename or name of an importable module).
161161
It should typically not contain any platform/runtime-specific extensions (``.exe``,``.so``,``.dll``,``.dylib``,``.py``, ``.sh``).
162162

163+
### Consumes Data / Produces Data
164+
165+
In addition to describing the type of the software, we define some vocabulary
166+
for allowing to describe the type of data that a certain software tool consumes
167+
(i.e. input) or produces (i.e. output). We focus only on high-level descriptions
168+
and not how particular data can be offered to, or obtained from, the software.
169+
The aim is to have a simple yet powerful way to express input and output data
170+
in software metadata.
171+
172+
We introduce the ``consumesData`` and ``producesData`` properties in our
173+
profile. The domain of these properties is `schema:SoftwareApplication` (or any
174+
of its subclasses) or `schema:SoftwareSourceCode`, the former is preferred as
175+
it is more specific and combines nicely with our use of `schema:targetProduct`.
176+
The range of the properties is a `schema:CreativeWork` (or any subclass),
177+
offering a high degree of flexibility and re-use of existing schema.org properties for
178+
e.g. expressing content/encoding types, natural languages etc...
179+
180+
Example C, describes software metadata for a fictitious speech recognition tool that takes an audio file and produces a textual transcription:
181+
182+
```json
183+
{
184+
"@context": [
185+
"https://raw.githubusercontent.com/codemeta/codemeta/2.0/codemeta.jsonld",
186+
"https://raw.githubusercontent.com/schemaorg/schemaorg/main/data/releases/13.0/schemaorgcontext.jsonld",
187+
"https://w3id.org/software-types"
188+
],
189+
"@type": "SoftwareSourceCode",
190+
"name": "MySpeechRecognizer",
191+
"codeRepository": "https://github.com/someuser/MySpeechRecognizer",
192+
...,
193+
"targetProduct": [
194+
{
195+
"type": "CommandLineApplication",
196+
"executableName": "transcribe",
197+
"name": "My Speech Recognition Tool",
198+
"runtimePlatform": "Linux"
199+
"consumesData": {
200+
"@type": "AudioObject",
201+
"encodingFormat": "audio/mp3",
202+
"inLanguage": {
203+
"@id": "https://iso639-3.sil.org/code/eng",
204+
"@type": "Language",
205+
"name": "English"
206+
"identifier": "eng",
207+
}
208+
},
209+
"producesData": {
210+
"@type": "TextDigitalDocument",
211+
"encodingFormat": "text/plain",
212+
"inLanguage": {
213+
"@id": "https://iso639-3.sil.org/code/eng",
214+
"@type": "Language",
215+
"name": "English"
216+
"identifier": "eng",
217+
}
218+
}
219+
},
220+
]
221+
}
222+
```
223+
224+
The two new properties may also be used directly on `SoftwareSourceCode`, but
225+
are simply interpreted less specific then (read as: *some undefined build
226+
target of the source code consumes/produces certain data*).
227+
228+
The properties we introduce here are deliberately limited: We do not tie the
229+
data to any endpoints or parameters. We deliberately do not specify by what
230+
means exactly the data can be offered to or obtained from the software. Our aim
231+
is not to provide a full machine-parseable specification of the input and
232+
output requirements of the software here; that would be up to other more
233+
complex initiatives like [OpenAPI](https://www.openapis.org) or
234+
[HydraCG](http://www.hydra-cg.com/spec/latest/core/). We merely enrich the
235+
metadata description so that data expectations can be communicated to the
236+
end-user.
237+
238+
In the data descriptions themselves, you can use any of the relevant properties
239+
already in schema.org. This already provides sufficient enough vocabulary to
240+
express data types, encoding formats, natural languages, possible licensing
241+
restrictions, etc...
242+
163243
## Implementations
164244

165245
Support for our `software_types` extension to codemeta/schema.org is

‎software-types.jsonld‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,8 @@
1212
"SoftwarePackage": { "@id": "stype:SoftwarePackage" },
1313
"NotebookApplication": { "@id": "stype:NotebookApplication" },
1414
"executableName": { "@id": "stype:executableName" },
15+
"producesData": { "@id": "stype:producesData" },
16+
"consumesData": { "@id": "stype:consumesData" },
1517
"targetProduct": { "@id": "schema:targetProduct" },
1618
"hasSourceCode": { "@id": "schema:hasSourceCode" },
1719
"WebAPI": { "@id": "schema:WebAPI" },
@@ -84,6 +86,18 @@
8486
"@type": "Property",
8587
"label": "Executable Name",
8688
"comment": "The name of the executable within a certain run-time context (e.g. an executable filename or name of an importable module)."
89+
},
90+
{
91+
"@id": "stype:consumesData",
92+
"@type": "Property",
93+
"label": "Consumes Data",
94+
"comment": "Links to creative works that may be consumed by the software (i.e. act as input). The further properties and exact subtype of the creative work narrows the scope, acting like a template."
95+
},
96+
{
97+
"@id": "stype:producesData",
98+
"@type": "Property",
99+
"label": "Produces Data",
100+
"comment": "Links to creative works that may be produced by the software (i.e. act as output). The further properties and exact subtype of the creative work narrows the scope, acting like a template."
87101
}
88102
]
89103
}

0 commit comments

Comments
 (0)