Hydrilla

// 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

}