summaryrefslogtreecommitdiff
path: root/src/test/example_content/hello/index.json
blob: 12105c20138284e851d4ef1341246d9359280508 (about) (plain)
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
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
// SPDX-License-Identifier: CC0-1.0

// Copyright (C) 2021 Wojtek Kosior
// Available under the terms of Creative Commons Zero v1.0 Universal.

// This is an example index.json file describing Hydrilla site content. As you
// can see, for storing site content information Hydrilla utilizes JSON with an
// additional extension in the form of '//' comments support. Hydrilla shall
// look into each direct subdirectory of the content directory passed to it
// (via a cofig file option). If such subsirectory contains an index.json file,
// Hydrilla shall process it.

// An index.json file conveys definitions of site resources, pattern->payload
// mappings and licenses thereof. The definitions may reference files under
// index.json's containing directory, using relative paths. This is how scripts,
// license texts, etc. are included. 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 be stripped when the file
// is processed. If a comment should be included in the JSON definitions served
// by Hydrilla API, it should be put in a "comment" field of the proper object.

// Various kinds of objects contain version information. Version is always an
// array of integers, with major version number being the first array item. When
// applicable, a 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.

{
    // Once our json schema changes, this version will change. Our software will
    // be able to handle both current and older formats thanks to this
    // information present in every index.json file. Different schema versions
    // are always incompatible (e.g. a Hydrilla instance that understands schema
    // version 0.2.0.0 will not understand version 0.2.0.1). Schemas that are
    // backwards-compatible will be denoted by a different revision.
    // We will try to make schema version match the version of Hydrilla software
    // that introduced it.
    "schema_version": [0, 2],
    "schema_revision": 1,

    // Copyright of this json file. It's a list of copyright holder information
    // objects. Alternatively, "auto" can be used to make Hydrilla attempt to
    // extract copyright info from the comment at the beginning of the file.
    "copyright":  [
	// There can be multiple entries, one for each co-holder of the
	// copyright.
	{
	    // There can also be multiple years, like ["2021","2023-2024"].
	    "years": ["2021"],
	    // Name of the copyright holder. Depending on the situation it can
	    // be just the first name, name+surname, a company name, a
	    // pseudonym, etc.
	    "holder": "Wojtek Kosior"
	}
    ],

    // License of this json file. Identifier has to be known to Hydrilla. Can
    // be defined either in the same or another index.json file as a "license"
    // item. It is possible to specify license combinations, like:
    // [["Expat", "and", "Apache-2.0"], "or", "GPL-3.0-only"]
    // Alternatively, "auto" can be used to make Hydrilla attempt to extract
    // copyright info from this file's SPDX license identifier.
    "licenses": "CC0-1.0",

    // Where this software/work initially comes from. In some cases (i.e. when
    // the developer of content is also the one who packages it for Hydrilla)
    // this might be the same as "package_url".
    "upstream_url": "https://git.koszko.org/pydrilla/tree/src/test/example_content/hello",

    // Where sources for the packaging of this content can be found.
    "package_url": "https://git.koszko.org/pydrilla/tree/src/test/example_content/hello",

    // Additional "comment" field can be used if needed.
    // "comment": ""

    // List of actual site resources, pattern->payload mappings and licenses.
    // 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", "license"
	    // and "mapping". The one we have here, "resource", 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",

	    // 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-zA-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",

	    // 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
	    // require that each resource has a uuid associated with it. Attempt
	    // to define multiple resources with the same identifier and
	    // different uuids will result in an error being reported. Defining
	    // multiple resources 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).
	    "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. Hydrilla
	    // will allow multiple definitions of the same resource to load, as
	    // long as their versions differ. Thanks to the "version" and
	    // "revision" fields, clients will know they have to update certain
	    // resource after it has been updated. If multiple definitions of
	    // the same version of given resource are provided, 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",

	    // If needed, a "comment" field can be added to provide some
	    // additional information.
	    // "comment": "this resource something something",

	    // One should specify the copyright and licensing terms of the
	    // entire package. The format is the same as when specifying these
	    // for the index.json file, except "auto" cannot be used.
	    "copyright": [{"years": ["2021"], "holder": "Wojtek Kosior"}],
	    "licenses": "CC0-1.0",

	    // 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": ["hello-message"],

	    // Array of javascript files that belong to this resource.
	    "scripts": [
		{
		    // Script name. It should also be a valid file path.
		    "name": "hello.js",
		    // Copyright and license info of a script file can be
		    // specified using the same format as in the case of the
		    // index.json file itself. If "copyright" or "license" is
		    // not provided, Hydrilla assumes it to be the same as the
		    // value specified for the resource itself.
		    "copyright": "auto",
		    "licenses":  "auto"
		}, {
		    "name":   "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",
	    "copyright":   [{"years": ["2021"], "holder": "Wojtek Kosior"}],
	    "licenses":    "CC0-1.0",
	    // If "dependencies" is empty, it can also be omitted.
	    // "dependencies": [],
	    "scripts": [{"name": "message.js"}]
	}, {
	    "type": "mapping",

	    // Has similar function to resource's identifier. Should be consize
	    // and can only use a restricted set of characters. It has to match:
	    // [-0-9a-zA-Z]
	    // It can be the same as some resource 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. 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": "54d23bba-472e-42f5-9194-eaa24c0e3ee7",

	    // "version" differs from its counterpart in resource in that it has
	    // no accompanying revision number.
	    "version": [2021, 11, 10],

	    // A short, meaningful description of what the mapping does.
	    "description": "causes apple to get greeted on Hydrillabugs issue tracker",

	    // A comment, if necessary.
	    // "comment": "blah blah because bleh"

	    // The "payloads" array specifies, which payloads are to be
	    // applied to which URLs.
	    "payloads": [
		{
		    // Should be a valid Haketilo URL pattern.
		    "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.
		    "payload": "helloapple"
		},
		// More associations may follow.
		{
		    "pattern": "https://hachettebugs.koszko.org/***",
		    "payload": "helloapple"
		}
	    ]
	}, {
	    "type": "license",

	    // Will be used to refer to this license in other places. Should
	    // match the SPDX identifier if possible (despite that, please use
	    // "Expat" instead of "MIT" where possible). Unlike other definition
	    // types, "license" does not allow uuids to be used to avoid license
	    // id clashes. Any attempt to define multiple licenses with the same
	    // id will result in an error being reported.
	    "identifier": "CC0-1.0",

	    // This long name must also be unique among all license definitions.
	    "long_name": "Creative Commons Zero v1.0 Universal",

	    // We don't use "version" in license definitions. We do, however,
	    // use "revision" to indicate changes to the packaging of a license.
	    // Revision should be increased by 1 at each such change.
	    "revision": 2,

	    "legal_text": [
		// Legal text can be available in multiple forms. Usually just
		// plain .txt file is enough, though.
		{
		    // "format" should match an agreed-upon MIME type if
		    // possible.
		    "format": "text/plain",
		    // Value of "file" should be a path relative to the
		    // directory of index.json file.
		    "file":   "cc0.txt"
		}
		// If a markdown version of CC0 was provided, we could add this:
		// {
		//     "format": "text/markdown",
		//     "file": "cc0.md"
		// }
	    ]

	    // If needed, a "comment" field can be added to clarify something.
	    // For example, when definind "Expat" license we could add:
	    //
	    // "comment": "Expat license is the most common form of the license often called \"MIT\". Many other forms of \"MIT\" license exist. Here the name \"Expat\" is used to avoid ambiguity."

	    // If applicable, a "notice" can be included. It shall then be a
	    // path (relative to index.json) to a plain text file with that
	    // notice.
	    //
	    // "notice": "license-notice.txt"
	    //
	    // This is needed for example in case of GNU licenses (both with and
	    // without exceptions). For example,
	    // "GPL-3.0-or-later-with-html-exception" could have the following
	    // in its notice file:
	    //
	    // This program is free software: you can redistribute it and/or
	    // modify it under the terms of the GNU General Public License as
	    // published by the Free Software Foundation, either version 3 of
	    // the License, or (at your option) any later version.
	    //
	    // This program is distributed in the hope that it will be useful,
	    // but WITHOUT ANY WARRANTY; without even the implied warranty of
	    // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
	    // GNU General Public License for more details.
	    //
	    // As a special exception to the GPL, any HTML file which merely
	    // makes function calls to this code, and for that purpose
	    // includes it by reference shall be deemed a separate work for
	    // copyright law purposes.  If you modify this code, you may extend
	    // this exception to your version of the code, but you are not
	    // obligated to do so.  If you do not wish to do so, delete this
	    // exception statement from your version.
	    //
	    // You should have received a copy of the GNU General Public License
	    // along with this program.  If not, see
	    // <https://www.gnu.org/licenses/>.
	}
    ]
}