1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
|
// SPDX-License-Identifier: CC0-1.0
// Copyright (C) 2021, 2022 Wojtek Kosior <koszko@koszko.org>
// Available under the terms of Creative Commons Zero v1.0 Universal.
// This is an example index.json file describing Hydrilla packages. As you can
// see, for storing this information Hydrilla utilizes JSON with an additional
// extension in the form of '//' comments support.
// An index.json file conveys definitions of site resources and pattern->payload
// mappings. The definitions may reference files under index.json's containing
// directory, using relative paths. This is how scripts, license texts, etc. are
// included.
// File reference always takes the form of an object with "file" property
// specifying path to the file. In certain contexts additional properties may be
// allowed or required. Unix paths (using '/' as separator) are assumed. It is
// not allowed for an index.json file to reference files outside its directory.
// Certain objects are allowed to contain a "comment" field. Although '//'
// comments can be used in index.json files, they will not be included in
// generated JSON definitions. If a comment should be included in the
// definitions served by Hydrilla API, it should be put in a "comment" field of
// the proper object.
// Unknown object properties will be ignored. This is for compatibility with
// possible future revisions of the format.
{
// Once our index.json schema changes, this field's value will change. Our
// software will be able to handle both current and older formats thanks to
// this information present in every index.json file. Schemas that differ by
// the first (major) number are always incompatible (e.g. a Hydrilla builder
// instance released at the time of 1.2 being the most recent schema version
// will not understand version 2.1).
// Schemas that are backwards-compatible will have the same major number
// and might differ by the second (minor) version number. The third (patch)
// and subsequent numbers are being ignored right now.
"$schema": "https://hydrilla.koszko.org/schemas/package_source-1.schema.json",
// Used when referring to this source package. Should be consize, unique
// (among other source package names) and can only use a restricted set of
// characters. It has to match: [-0-9a-z.]+
"source_name": "hello",
// This property lists files that contain copyright information regarding
// this source package as well as texts of licenses used. Although no
// specific format of these files is mandated, it is recommended to make
// each source package REUSE-compliant, generate an spdx report for it as
// `report.spdx` and list this report together with all license files here.
"copyright": [
{"file": "report.spdx"},
{"file": "LICENSES/CC0-1.0.txt"}
],
// Where this software/work initially comes from.
"upstream_url": "https://git.koszko.org/hydrilla-source-package-example",
// Additional "comment" field can be used if needed.
// "comment": ""
// List of actual site resources and pattern->payload mappings. Each of them
// is represented by an object. Meta-sites and replacement site interfaces
// will also belong here once they get implemented.
"definitions": [
{
// Value of "type" can currently be one of: "resource", "mapping"
// and "mapping_and_resource" for a combined definition. The one we
// have here, "mapping", associates resources with pages on which
// they are to be used.
"type": "mapping",
// Used when referring to this mapping in "required_mappings" list
// of another item. Should be consize and can only use a restricted
// set of characters. It has to match: [-0-9a-z]+
"identifier": "helloapple",
// "long_name" should be used to specify a user-friendly alternative
// to an identifier. It should generally not collide with a long
// name of some resource with a different UUID and also shouldn't
// change in-between versions of the same resource, although
// exceptions to both rules might be considered. Long name is
// allowed to contain arbitrary unicode characters (within reason!).
"long_name": "Hello Apple",
// Item definitions contain version information. Version is
// represented as an array of integers, with major version number
// being the first array item. In case of resources, version is
// accompanied by a revision field which contains a positive
// integer. If versions specified by arrays of different length need
// to be compared, the shorter array gets padded with zeroes on the
// right. This means that for example version 1.3 could be given as
// both [1, 3] and [1, 3, 0, 0] (aka 1.3.0.0) and either would mean
// the same.
// Different versions (e.g. 1.0 and 1.3) of the same resource can be
// defined in separate index.json files. This makes it easy to
// accidently cause an identifier clash. To help detect it, we allow
// each item to have a UUID associated with it. Attempt to define
// multiple mapping with the same identifier and different UUIDs
// will result in an error being reported. Defining multiple
// mappings with different identifiers and the same UUID is
// disallowed for now (it may be later permitted if we consider it
// good for some use-case).
// As of package source schema version 2.0, UUIDs are optional and
// can be omitted.
"uuid": "54d23bba-472e-42f5-9194-eaa24c0e3ee7",
// Thanks to the "version" field (and "revision" field in case of
// "resource" or "mapping_and_resource", clients will know they have
// to update certain item after a new version has appeared in the
// repository. If multiple definitions of the same version of given
// item are provided to Hydrilla server, an error is generated.
// "version" differs from its counterpart in resource in that it has
// no accompanying revision number. For combined definitions with
// "mapping_and_resource" as type, the value of "revision" is
// appended as the last component of the resulting mapping's
// version. If type is simply "mapping", revision number is ignored.
"version": [2021, 11, 10],
// A short, meaningful description of what the mapping does.
"description": "causes apple to get greeted on Hydrillabugs issue tracker",
// If needed, a "comment" field can be added to provide some
// additional information.
// "comment": "this resource something something",
// The "payloads" object specifies which payloads are to be applied
// to which URLs.
"payloads": {
// Each key should be a valid Haketilo URL pattern.
"https://hydrillabugs.koszko.org/***": {
// Should be the name of an existing resource. The resource
// may, but doesn't have to, be defined in the same
// index.json file.
"identifier": "helloapple"
},
// More associations may follow.
"https://hachettebugs.koszko.org/***": {
"identifier": "helloapple"
}
}
}, {
// A "resource" item defines a list of injectable scripts that can
// be used as a payload or as a dependency of another "resource". In
// the future CSS style sheets and WASM modules will also be
// composite parts of a "resource" as scripts are now.
"type": "resource",
// Has similar function to mapping's identifier. Used when
// referring to this resource in "dependencies" list of another
// resource or in "payload" field of a mapping. Should be consize
// and can only use a restricted set of characters. It has to match:
// [-0-9a-z]+
// It can be the same as some mapping identifier (those are
// different entities and are treated separately).
"identifier": "helloapple",
// "long name" and "uuid" have the same meaning as in the case of
// resources and "uuid" is also optional. UUIDs of a resource and a
// mapping can technically be the same but it is recommended to
// avoid even this kind of repetition.
"long_name": "Hello Apple",
"uuid": "a6754dcb-58d8-4b7a-a245-24fd7ad4cd68",
// Version should match the upstream version of the resource (e.g. a
// version of JavaScript library). Revision number starts as 1 for
// each new resource version and gets incremented by 1 each time a
// modification to the packaging of this version is done.
// If multiple definitions of the same version of given resource are
// provided to Hydrilla server, an error is generated (even if those
// definitions differ by revision number).
"version": [2021, 11, 10],
"revision": 1,
// A short, meaningful description of what the resource is and/or
// what it does.
"description": "greets an apple",
// A comment, if necessary.
// "comment": "blah blah because bleh"
// Resource's "dependencies" array shall contain names of other
// resources that (in case of scripts at least) should get evaluated
// on a page before this resource's own scripts.
"dependencies": [{"identifier": "hello-message"}],
// Array of JavaScript files that belong to this resource.
"scripts": [
{"file": "hello.js"},
{"file": "bye.js"}
]
}, {
"type": "resource",
"identifier": "hello-message",
"long_name": "Hello Message",
"uuid": "1ec36229-298c-4b35-8105-c4f2e1b9811e",
"version": [2021, 11, 10],
"revision": 2,
"description": "define messages for saying hello and bye",
// If "dependencies" is empty, it can also be omitted.
// "dependencies": [],
"scripts": [{"file": "message.js"}]
}
],
// We can also list additional files to include in the produced source
// archive. Hydrilla builder will then include those together with all
// script and copyright files used.
"additional_files": [
{"file": "README.txt"},
{"file": "README.txt.license"},
{"file": ".reuse/dep5"}
],
// We can optionally tell Hydrilla builder to run the REUSE tool to generate
// report.spdx file. Using this option requires REUSE to be installed and
// and importable in the Python virtualenv used by Hydrilla builder.
"reuse_generate_spdx_report": true
}
|
