Skip to content

Commit ffea5e4

Browse files
rubensworksrubensworks
committed
Update to Components.js 3.0.0 with import URL changes
1 parent 2accf4f commit ffea5e4

File tree

15 files changed

+84
-30
lines changed

15 files changed

+84
-30
lines changed

‎components/MarkdownPage.jsonld

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
{
2-
"@context": "https://linkedsoftwaredependencies.org/contexts/documentation-components.jsonld",
2+
"@context": "https://linkedsoftwaredependencies.org/bundles/npm/documentation-components/^1.0.0/components/context.jsonld",
33
"@id": "npmd:documentation-components",
44
"components": [
55
{

‎components/Page.jsonld

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
{
2-
"@context": "https://linkedsoftwaredependencies.org/contexts/documentation-components.jsonld",
2+
"@context": "https://linkedsoftwaredependencies.org/bundles/npm/documentation-components/^1.0.0/components/context.jsonld",
33
"@id": "npmd:documentation-components",
44
"components": [
55
{

‎components/PageLogger.jsonld

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
{
2-
"@context": "https://linkedsoftwaredependencies.org/contexts/documentation-components.jsonld",
2+
"@context": "https://linkedsoftwaredependencies.org/bundles/npm/documentation-components/^1.0.0/components/context.jsonld",
33
"@id": "npmd:documentation-components",
44
"components": [
55
{

‎components/PageServer.jsonld

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
{
2-
"@context": "https://linkedsoftwaredependencies.org/contexts/documentation-components.jsonld",
2+
"@context": "https://linkedsoftwaredependencies.org/bundles/npm/documentation-components/^1.0.0/components/context.jsonld",
33
"@id": "npmd:documentation-components",
44
"components": [
55
{

‎components/components.jsonld

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
{
2-
"@context": "https://linkedsoftwaredependencies.org/contexts/documentation-components.jsonld",
2+
"@context": "https://linkedsoftwaredependencies.org/bundles/npm/documentation-components/^1.0.0/components/context.jsonld",
33
"@id": "npmd:documentation-components",
44
"@type": "Module",
55
"requireName": "documentation-components",
66
"import": [
7-
"Page.jsonld",
8-
"PageLogger.jsonld",
9-
"PageServer.jsonld",
10-
"MarkdownPage.jsonld"
7+
"files-dc:components/Page.jsonld",
8+
"files-dc:components/PageLogger.jsonld",
9+
"files-dc:components/PageServer.jsonld",
10+
"files-dc:components/MarkdownPage.jsonld"
1111
]
1212
}

‎components/context.jsonld

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,10 @@
11
{
22
"@context": [
3-
"https://linkedsoftwaredependencies.org/contexts/components.jsonld",
3+
"https://linkedsoftwaredependencies.org/bundles/npm/componentsjs/^3.0.0/components/context.jsonld",
44
{
55
"npmd": "https://linkedsoftwaredependencies.org/bundles/npm/",
66
"dc": "npmd:documentation-components/",
7+
"files-dc": "dc:^1.0.0/",
78

89
"Page": "dc:Page",
910

‎config/log_page.jsonld

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
{
2-
"@context": "https://linkedsoftwaredependencies.org/contexts/documentation-components.jsonld",
2+
"@context": "https://linkedsoftwaredependencies.org/bundles/npm/documentation-components/^1.0.0/components/context.jsonld",
33
"@id": "urn:components:documentation",
44
"@type": "PageLogger",
55
"logPage": {

‎config/serve_page.jsonld

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
{
2-
"@context": "https://linkedsoftwaredependencies.org/contexts/documentation-components.jsonld",
2+
"@context": "https://linkedsoftwaredependencies.org/bundles/npm/documentation-components/^1.0.0/components/context.jsonld",
33
"@id": "urn:components:documentation",
44
"@type": "PageServer",
55
"servePage": {

‎docs/configuration/components/general.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,10 @@ Components can be configured using the following types and predicates:
1717
| constructorArguments | oo:constructorArguments | oo:Component → rdf:list of om:ObjectMapping | Defines the list of constructor arguments of a given component. These arguments must be ObjectMappings. If this is not provided, the parameter values are passed to the constructor as a raw hash. |
1818
| extends | rdfs:subClassOf | oo:Component → oo:Component | Say that a certain component extends from another component, which will inherit all its parameters. |
1919
| requireElement | oo:componentPath | oo:Component → xsd:string | The object path to a module delimited by `.`. For example, the path to element `X` in object `{ a: { b: { X: { ... } } } }` is `a.b.X`. |
20+
| import | owl:imports | ? → ? | Includes the target file (URL) in this file. |
21+
22+
!!! note
23+
More information on importing can be found on the [modules configuration page](/configuration/modules/).
2024

2125
## Example: Abstract Component
2226

‎docs/configuration/general.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,6 @@ The following vocabularies are understood by Components.js:
5353
| owl | http://www.w3.org/2002/07/owl# |
5454
| xsd | http://www.w3.org/2001/XMLSchema# |
5555

56-
If the JSON-LD serialization is used, shortcuts can be used for most of the URLs using Components.js's context: [https://linkedsoftwaredependencies.org/contexts/components.jsonld](https://linkedsoftwaredependencies.org/contexts/components.jsonld)
56+
If the JSON-LD serialization is used, shortcuts can be used for most of the URLs using Components.js's context: [https://linkedsoftwaredependencies.org/bundles/npm/componentsjs/^3.0.0/components/context.jsonld](https://linkedsoftwaredependencies.org/bundles/npm/componentsjs/^3.0.0/components/context.jsonld)
5757

5858
These vocabularies will be referenced by their prefix and JSON-LD shortcut in the following sections.

‎docs/configuration/modules.md

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ Modules can be configured using the following type and predicates:
1111
| JSON-LD Shortcut | URI | Domain → Range | Description |
1212
| -------------------- | ----------------------- | ------------------------------------------- | ----------- |
1313
| components | oo:component | oo:Module → oo:Component | Attaches one or more components to a module. |
14-
| import | owl:imports | ? → xsd:string | Includes the target file (local path or URL) in this file. |
14+
| import | owl:imports | ? → ? | Includes the target file (URL) in this file. |
1515
| requireName | doap:name | oo:Module → xsd:string | The name of the npm package as defined in the `package.json` file. |
1616
| comment | rdfs:comment | ? → xsd:string | The comment of a thing. |
1717

@@ -20,7 +20,7 @@ Modules can be configured using the following type and predicates:
2020
A module can be defined as follows:
2121
```json
2222
{
23-
"@context": "https://linkedsoftwaredependencies.org/contexts/components.jsonld",
23+
"@context": "https://linkedsoftwaredependencies.org/bundles/npm/componentsjs/^3.0.0/components/context.jsonld",
2424
"@id": "http://example.org/MyModule",
2525
"@type": "Module",
2626
"requireName": "my-module",
@@ -29,9 +29,11 @@ A module can be defined as follows:
2929
...
3030
],
3131
"import": [
32-
"path/to/some/component.jsonld",
33-
"other/component/in/another/serialization.ttl",
34-
"http://example.org/yet/another/component.jsonld"
32+
"http://example.org/path/to/some/component.jsonld",
33+
"http://example.org/other/component/in/another/serialization.ttl"
3534
]
3635
}
3736
```
37+
38+
!!! note
39+
Import sources [can be overriden using the `lsd:importPaths` entry](/getting_started/basics/exposing_components/) in your `package.json` file.

‎docs/getting_started/basics/exposing_components.md

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,8 @@ For example:
2323
}
2424
```
2525

26+
### Advanced: Context overriding
27+
2628
Optionally, a [JSON-LD context file](https://www.w3.org/TR/json-ld/#the-context) can be linked as well,
2729
which allows this context to be dereferenced locally:
2830
```json
@@ -38,3 +40,33 @@ which allows this context to be dereferenced locally:
3840
As this can lead to some overhead, Components.js can automatically wire contexts together if they are defined in `package.json` files.
3941
Instead of resolving the context via HTTP(S), the context will be fetched from the local file system instead,
4042
as defined by the npm modules.
43+
44+
!!! note
45+
If your package is available on [npm](https://www.npmjs.com/), and you have properly used the `lsd:components` entry in your `package.json` file,
46+
then your context file will automatically be published on the [Linked Software Dependencies npm mirror](https://linkedsoftwaredependencies.org/).
47+
The URL of your context file is `https://linkedsoftwaredependencies.org/bundles/npm/[packagename]/[version or range]/components/context.jsonld`.
48+
For example, the latest context file of Components.js is available at `https://linkedsoftwaredependencies.org/bundles/npm/componentsjs/*/components/context.jsonld`.
49+
In that case, you are encouraged to use these URLs as keys `lsd:contexts`.
50+
51+
### Advanced: Import overriding
52+
53+
Similar to context file overriding, import paths can also be overridden.
54+
This is useful when you want to avoid expensive HTTP lookups for files in cases where you have the relevant files available locally.
55+
Additionally, this can be used during development when you make changes to your imported file that has not been made available via its URL (yet).
56+
57+
The `lsd:importPaths` refers to a hash that maps URL prefixes to local path prefixes:
58+
```json
59+
{
60+
"lsd:importPaths": {
61+
"http://example.org/myconfig.jsonld": "config/myconfig.jsonld",
62+
"http://example.org/otherconfigs/": "config/otherconfigs/",
63+
},
64+
}
65+
```
66+
67+
!!! note
68+
If your package is available on [npm](https://www.npmjs.com/),
69+
then your import paths will automatically be published on the [Linked Software Dependencies npm mirror](https://linkedsoftwaredependencies.org/).
70+
The URL of this will be `https://linkedsoftwaredependencies.org/bundles/npm/[packagename]/[version or range]/[importPathValue]`.
71+
For example, the latest version of `@comunica/actor-init-hello-world` with import path value `config/` will be exposed at `https://linkedsoftwaredependencies.org/bundles/npm/@comunica/actor-init-hello-world/*/config/`.
72+
In that case, you are encouraged to use these URLs as keys `lsd:importPaths`.

‎docs/getting_started/basics/workflow.md

Lines changed: 20 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ As we only define a module here, no dependency on Components.js needs to be adde
1616
The contents of a module file looks as follows:
1717
```json
1818
{
19-
"@context": "https://linkedsoftwaredependencies.org/contexts/components.jsonld",
19+
"@context": "https://linkedsoftwaredependencies.org/bundles/npm/componentsjs/^3.0.0/components/context.jsonld",
2020
"@id": "http://example.org/MyModule",
2121
"@type": "Module",
2222
"requireName": "my-module"
@@ -35,7 +35,7 @@ The contents of a module file looks as follows:
3535

3636
{
3737
"@context": [
38-
"https://linkedsoftwaredependencies.org/contexts/components.jsonld",
38+
"https://linkedsoftwaredependencies.org/bundles/npm/componentsjs/^3.0.0/components/context.jsonld",
3939
{ "ex": "http://example.org/" }
4040
],
4141
"@id": "ex:MyModule",
@@ -50,7 +50,7 @@ All available entries of a module can be found [here](../../configuration/module
5050
#### @id
5151

5252
The `@id` contains the unique URI of your module, which *should* be dereferencable.
53-
If your module is publicly available on npm, you can use its automatically generated URL `https://linkedsoftwaredependencies.org/bundles/npm/my-module`.
53+
If your module is publicly available on npm, you can use its automatically generated URL `https://linkedsoftwaredependencies.org/bundles/npm/[my-module]`.
5454

5555
!!! note
5656
[https://linkedsoftwaredependencies.org/bundles/npm/](https://linkedsoftwaredependencies.org/bundles/npm/) is a semantic mirror of all available packages on npm.
@@ -71,7 +71,7 @@ Following the module from last section, the contents of a components file looks
7171
```json
7272
{
7373
"@context": [
74-
"https://linkedsoftwaredependencies.org/contexts/components.jsonld",
74+
"https://linkedsoftwaredependencies.org/bundles/npm/componentsjs/^3.0.0/components/context.jsonld",
7575
{ "ex": "http://example.org/" }
7676
],
7777
"@id": "ex:MyModule",
@@ -112,24 +112,36 @@ but when multiple components are available, separate files for each component sh
112112
When separate component files are created, they must be included in the main module file as follows:
113113
```json
114114
{
115-
"@context": "https://linkedsoftwaredependencies.org/contexts/components.jsonld",
115+
"@context": "https://linkedsoftwaredependencies.org/bundles/npm/componentsjs/^3.0.0/components/context.jsonld",
116116
"@id": "http://example.org/MyModule",
117117
...
118118
"import": [
119-
"MyComponent.jsonld",
120-
"MyOtherComponent.jsonld"
119+
"http://example.org/MyModule/MyComponent.jsonld",
120+
"http://example.org/MyModule/MyOtherComponent.jsonld"
121121
]
122122
}
123123
```
124124

125+
As you can see, these import values are URLs.
126+
As a best-practise, the contents of this URL should correspond to your file.
127+
But when you are still developing, this may not be possible yet.
128+
In this case, you can use the `lsd:importPaths` in your `package.json` file
129+
to override the URL with a local file path as follows:
130+
```json
131+
"lsd:importPaths": {
132+
"http://example.org/MyModule/": "components/",
133+
},
134+
```
135+
More information on this can be found on page on [exposing components](/getting_started/basics/exposing_components/#advanced-import-overriding).
136+
125137
### 3. Component configuration file
126138

127139
Component configuration files represent the semantic instantiation of a component.
128140
These can look as follows:
129141
```json
130142
{
131143
"@context": [
132-
"https://linkedsoftwaredependencies.org/contexts/components.jsonld",
144+
"https://linkedsoftwaredependencies.org/bundles/npm/componentsjs/^3.0.0/components/context.jsonld",
133145
{ "ex": "http://example.org/" }
134146
],
135147
"@id": "ex:myInstance",

‎docs/index.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ $ npm install componentsjs
4343
```json
4444
{
4545
"@context": [
46-
"https://linkedsoftwaredependencies.org/contexts/components.jsonld",
46+
"https://linkedsoftwaredependencies.org/bundles/npm/componentsjs/^3.0.0/components/context.jsonld",
4747
{ "ex": "http://example.org/" }
4848
],
4949
"@id": "ex:MyModule",
@@ -75,7 +75,7 @@ The constructor of `MyComponent` takes a single `name` argument.
7575
```json
7676
{
7777
"@context": [
78-
"https://linkedsoftwaredependencies.org/contexts/components.jsonld",
78+
"https://linkedsoftwaredependencies.org/bundles/npm/componentsjs/^3.0.0/components/context.jsonld",
7979
{
8080
"ex": "http://example.org/",
8181
"name": "ex:MyModule/MyComponent#name"

‎package.json

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,10 @@
55
"lsd:module": "https://linkedsoftwaredependencies.org/bundles/npm/documentation-components",
66
"lsd:components": "components/components.jsonld",
77
"lsd:contexts": {
8-
"https://linkedsoftwaredependencies.org/contexts/documentation-components.jsonld": "components/context.jsonld"
8+
"https://linkedsoftwaredependencies.org/bundles/npm/documentation-components/^1.0.0/components/context.jsonld": "components/context.jsonld"
9+
},
10+
"lsd:importPaths": {
11+
"https://linkedsoftwaredependencies.org/bundles/npm/documentation-components/^1.0.0/components/": "components/"
912
},
1013
"bin": {
1114
"serve": "./bin/serve.js"
@@ -16,7 +19,7 @@
1619
"license": "MIT",
1720
"private": true,
1821
"dependencies": {
19-
"componentsjs": "^2.0.0",
22+
"componentsjs": "^3.0.0",
2023
"remark": "^8.0.0",
2124
"remark-html": "^6.0.1"
2225
}

0 commit comments

Comments
 (0)