Every rule that publiccode-parser-go
applies to a publiccode.yml v0.x file, and how it maps onto this JSON Schema.
- Source: parser
mainate122415(v5.4.3 + 31 commits; the last ones only touch CI, docs, the CLI, the file name in diagnostics and the iPA code list). Note: commit9fe860cmarks the parser repository as unmaintained. - The editor (
publiccode-editor/src/wasm/go.mod) pins v5.4.3, not v5.2.1. The Since column marks rules that appeared after v5.2.1, so both versions can be compared. - The editor runs the parser with
DisableNetwork: true(but external checks enabled): see Network and file checks. - v1 (
publiccodeYmlVersion: "1", still a skeleton upstream) is out of scope.
Legend for Schema @ main (the publiccode-schema-v0.5.0.json generated from main):
✅ covered ·
Legend for How:
- JSON – plain JSON Schema (draft-07).
- format – a custom Ajv format (implemented in the editor, see
Custom formats). Vocabularies are generated from the Go
libraries by
scripts/vocabintodata/vocab/. - keyword – Ajv re-implements a standard keyword with parser semantics.
- TS – needs code outside the schema (the editor's
checksmodule).
These run before anything else; on failure the parser returns only this error.
| Rule | Key | Level | Schema @ main | How | Since |
|---|---|---|---|---|---|
| Input must be valid UTF-8 | "" |
error | n/a | TS (YAML layer) | |
| YAML syntax errors | "" |
error | n/a | TS (YAML layer) | |
| Only one YAML document per file | "" |
error | n/a | TS (YAML layer) | |
publiccodeYmlVersion present (also when the document is empty) |
publiccodeYmlVersion |
error | ✅ required | TS (pre-check, to stop early like the parser) | |
publiccodeYmlVersion must be a YAML string (0.2 unquoted → "wrong type for this field") |
publiccodeYmlVersion |
error | ✅ type: string |
TS pre-check | |
publiccodeYmlVersion in SupportedVersions (0, 0.2, 0.2.0, 0.2.1, 0.2.2, 0.3, 0.3.0, 0.4, 0.4.0, 0.5, 0.5.0, 0.7, 0.7.0) |
publiccodeYmlVersion |
error | 0.7, 0.7.0 |
JSON enum + TS pre-check | 0.7* in v5.4.0 |
| Rule | Key | Level | Schema @ main | How | Since |
|---|---|---|---|---|---|
Unknown keys are rejected (DisallowUnknownField), at every level |
the unknown key | error | additionalProperties:false everywhere except description.<lang> (broken, see §4) |
JSON | |
| Wrong YAML type for a field ("wrong type for this field") | first bad key | error | JSON type |
||
| Decoding stops at the first decode error; the struct validator then runs on the partially-decoded struct | — | — | n/a | Not reproducible: Ajv reports all errors. Expect extra "required" errors from the parser on such files | |
Any YAML scalar decodes into a string field (phone: +39…, genericName: 0123… are strings) |
— | — | ❌ numbers rejected | TS: numbers, and booleans outside boolean keys, become strings before validation | |
A key with no value (name:) is null and decodes to the zero value, so required fires (not a type error) |
the key | error | TS: drop nulls before validation | ||
isBasedOn accepts a string or a list of strings; a single string is reported as isBasedOn[0] |
isBasedOn |
— | ✅ (oneOf) |
JSON type: [string, array] |
|
A missing struct section (legal, maintenance, localisation) is reported on its required keys (legal.license, …) |
children | error | n/a | TS (error mapping) | |
Map keys are rendered description.en only for purely alphabetic tags, otherwise description[en-US] |
— | — | n/a | TS (error mapping) | |
Both IT and it are accepted keys (same ITSectionV0 struct) |
IT, it |
— | ❌ only IT; files with it: fail on the root additionalProperties:false |
JSON (add it) |
| Field | Tag(s) | Level | Schema @ main | How | Since |
|---|---|---|---|---|---|
publiccodeYmlVersion |
required,oneof=… |
error | JSON | ||
name |
required (non-empty string) |
error | JSON minLength: 1 |
||
url |
required,url_url |
error | format: uri (different semantics) |
format url_url |
|
landingURL |
url_http_url |
error | format: uri |
format url_http_url |
|
isBasedOn[*] |
url_url |
error | ❌ | format url_url |
|
releaseDate |
date (datetime=2006-01-02) |
error | ✅ format: date |
ajv-formats date |
|
inputTypes[*], outputTypes[*] |
is_mime_type |
error | ❌ | format mime_type |
|
platforms |
gt=0 (≥ 1 item; missing counts as 0) |
error | minItems; has an enum the parser does not enforce |
JSON minItems: 1, drop the enum |
|
categories[*] |
is_category_v0 |
error | ✅ enum | JSON enum | |
fundedBy[*] |
dive → organisation rules |
error | JSON $ref |
||
roadmap |
url_http_url |
error | format: uri |
format url_http_url |
|
developmentStatus |
required,oneof=concept development beta stable obsolete |
error | ✅ | JSON | |
softwareType |
required,oneof=… (9 values) |
error | ✅ | JSON | |
supports[*].id |
required,supports_id |
error | ❌ (supports missing → unknown key) |
JSON + format supports_id |
v5.4.0 |
intendedAudience.scope[*] |
is_scope_v0 |
error | ✅ enum | JSON enum | |
intendedAudience.countries[*], unsupportedCountries[*] |
iso3166_1_alpha2_lower_or_upper |
error | ^[A-Z]{2}$: rejects lowercase (only a warning in the parser), accepts unassigned codes |
format iso3166_1_alpha2_lower_or_upper |
|
description |
gt=0 (≥ 1 language; required) |
error | minProperties |
JSON minProperties: 1 |
|
description keys |
bcp47_keys (each key bcp47_strict_language_tag) |
error (key description) |
❌ | JSON propertyNames + format bcp47_strict_language_tag |
strict since v5.3.0 (was bcp47_language_tag) |
legal.license |
required,is_spdx_expression |
error | format spdx_expression |
||
maintenance.type |
required,oneof=internal contract community none |
error | ✅ | JSON | |
maintenance.contractors |
required_if=Type contract |
error | ❌ | JSON if/then |
|
maintenance.contractors |
excluded_unless=Type contract (validation of the items stops there) |
error | ❌ | JSON if/else with contractors: false; items validated only in the then branch |
|
maintenance.contacts |
required_if=Type community, required_if=Type internal |
error | ❌ | JSON if/then |
|
localisation.localisationReady |
required (non-nil bool) |
error | ✅ | JSON | |
localisation.availableLanguages |
required,gt=0 |
error | minItems |
JSON minItems: 1 |
|
localisation.availableLanguages[*] |
bcp47_strict_language_tag |
error | ❌ | format bcp47_strict_language_tag |
strict since v5.3.0 |
dependsOn.{open,proprietary,hardware}[*] |
dive → dependency rules |
error | ✅ | JSON $ref |
|
IT / it |
nested struct validated (see §5) | error | JSON $ref |
| Field | Tag(s) | Level | Schema @ main | How | Since |
|---|---|---|---|---|---|
description.<lang> (whole object) |
— | — | ❌ bug: the builder defines a property named additionalProperties, so language entries are not validated at all and any key is accepted |
JSON additionalProperties: {$ref} |
|
description.<lang>.genericName |
umax=35 (grapheme clusters) |
error | maxLength counts code points |
keyword maxLength = graphemes |
|
description.<lang>.shortDescription |
required,umax=150 |
error | JSON minLength: 1 + keyword |
||
description.<lang>.longDescription |
required,umin=150,umax=10000 (graphemes) |
error | JSON required + keyword | ||
description.<lang>.documentation, apiDocumentation |
url_http_url |
error | format: uri |
format url_http_url |
|
description.<lang>.features |
gt=0,dive (no omitempty: a missing list fails too) |
error | minItems |
JSON required + minItems: 1 |
|
description.<lang>.videos[*] |
url_http_url |
error | ❌ | format url_http_url |
|
maintenance.contractors[*].name |
required |
error | JSON minLength: 1 |
||
maintenance.contractors[*].until |
required,date |
error | ✅ | JSON + ajv-formats date |
|
maintenance.contractors[*].email |
email |
error | ❌ bug: format: date |
format email (parser regex) |
|
maintenance.contractors[*].website |
url_http_url |
error | format: uri |
format url_http_url |
|
maintenance.contacts[*].name |
required |
error | JSON minLength: 1 |
||
maintenance.contacts[*].email |
email |
error | format email (parser regex) |
||
dependsOn.*[*].name |
required,gt=0 |
error | JSON minLength: 1 |
||
dependsOn.*[*].version* |
*string (numbers decode as strings, lists/maps are wrong type) |
error (decode) | oneOf string/number |
JSON type: string + TS scalar normalisation |
|
organisation.uri, fundedBy[*].uri |
required,organisation_uri |
error | format: uri |
JSON required + format organisation_uri |
case-insensitive URN check since v5.3.1 |
supports[*].id |
required,supports_id |
error | ❌ | format supports_id |
v5.4.0 |
| Rule | Key | Level | Schema @ main | How | Since |
|---|---|---|---|---|---|
countryExtensionVersion oneof=0.2 1.0 |
IT.countryExtensionVersion |
error | JSON enum | ||
riuso.codiceIPA is_italian_ipa_code |
IT.riuso.codiceIPA |
error | ❌ | format italian_ipa_code |
|
conforme.*, piattaforme.* booleans |
error (decode) | ✅ | JSON | ||
Both IT and it present: "'IT' key already present. Remove this key" |
it |
error | ❌ | TS | |
it (lowercase) used: deprecated, use IT |
it |
warning | n/a | TS | |
IT.conforme present: deprecated |
IT.conforme |
warning | n/a | TS | |
IT.riuso.codiceIPA valid: deprecated, use organisation.uri: urn:x-italian-pa:<code> |
IT.riuso.codiceIPA |
warning | n/a | TS |
| Rule | Key | Level | Network? | Schema @ main | How | Since |
|---|---|---|---|---|---|---|
publiccodeYmlVersion is not 0 and not 0.7*: "vX is not the latest version, use '0'. Parsing this file as v0.7." |
publiccodeYmlVersion |
warning | no | n/a | TS | before v5.4.0 the exemption was 0.5* |
monochromeLogo present: deprecated, use logo |
monochromeLogo |
warning | no | n/a | TS | |
legal.authorsFile present: deprecated |
legal.authorsFile |
warning | no | n/a | TS | |
legal.repoOwner present: deprecated, use organisation.name |
legal.repoOwner |
warning | no | n/a | TS | |
inputTypes / outputTypes present: deprecated |
inputTypes, outputTypes |
warning | no | n/a | TS | |
description.<lang>.genericName non-empty: deprecated |
description.<lang>.genericName |
warning | no | n/a | TS | |
| Lowercase (valid) country code: deprecated, use uppercase | intendedAudience.countries[i], …unsupportedCountries[i] |
warning | no | n/a | TS | |
logo, monochromeLogo, legal.authorsFile, screenshots[i] must not be an absolute path (/…) or a file: URL |
same key | error | no | ❌ | TS (could be a JSON pattern, kept in TS for the message) |
|
Relative logo / monochromeLogo must end in .svg, .svgz or .png |
logo |
error | no (external checks) | ❌ | TS | |
Relative screenshots[i] must end in .jpg or .png |
description.<lang>.screenshots[i] |
error | no (external checks) | ❌ | TS | |
videos[i] must match an oEmbed provider scheme |
description.<lang>.videos[i] |
error | no | ❌ | TS (data/vocab/oembed-schemes.json) |
providers list shrunk in v5.3.0 |
Skipped by the editor (DisableNetwork: true), or no-ops in WASM
(runtime.GOARCH == "wasm" makes isReachable and fileExists return true):
| Rule | Key | Level | Skipped by |
|---|---|---|---|
url reachable and is a code repository (vcsurl.IsRepo) |
url |
error | DisableNetwork |
landingURL, roadmap, documentation, apiDocumentation reachable |
same | error | DisableNetwork |
Raw base URL derived from url (vcsurl.GetRawRoot) when no base URL is given |
url |
error | DisableNetwork |
logo / monochromeLogo file exists; PNG decodes |
logo |
error | WASM no-op / no network for remote files |
legal.authorsFile exists |
legal.authorsFile |
error | WASM no-op |
screenshots[i] exist |
…screenshots[i] |
error | WASM no-op |
| Minimum PNG logo width | logo |
error | removed in v5.3.1 |
These can't be done in the browser with JSON Schema anyway; a remote validator
(VITE_VALIDATOR_REMOTE_URL) is the place for them.
| Format | Parser tag | Semantics | Vocabulary |
|---|---|---|---|
url_url |
url_url → go-playground url |
lowercased net/url.Parse: needs a scheme; file: needs a path other than /; other schemes need a host, opaque part or fragment |
— |
url_http_url |
url_http_url → http_url |
url_url + non-empty host + scheme http/https |
— |
email |
email |
go-playground's e-mail regex | email-regex.json |
date |
date |
YYYY-MM-DD, real calendar date |
ajv-formats |
mime_type |
is_mime_type |
^ *([A-Za-z0-9][A-Za-z0-9!#$&^_-]{0,126})/([A-Za-z0-9][A-Za-z0-9!#$&^_.+-]{0,126}) *$ |
— |
spdx_expression |
is_spdx_expression |
go-spdx ValidateLicenses: active or deprecated IDs (case-insensitive), +, WITH exceptions, AND/OR, parentheses, LicenseRef-/DocumentRef- |
spdx.json (go-spdx v2.7.0) |
bcp47_strict_language_tag |
bcp47_strict_language_tag |
RFC 5646 grammar + known language (x/text), extlang prefixes, script, region (ISO 3166 / M.49 subset), registered variants | bcp47.json (x/text v0.37.0, validator v10.30.3) |
iso3166_1_alpha2_lower_or_upper |
same | all-lower or all-upper, assigned ISO 3166-1 alpha-2 code | countries.json |
italian_ipa_code |
is_italian_ipa_code |
case-insensitive membership | ipa-codes.json (parser v5.4.3) |
organisation_uri |
organisation_uri |
ParseRequestURI; URN → urn_rfc2141 and, for urn:x-italian-pa:, a known iPA code; otherwise scheme + host |
ipa-codes.json |
supports_id |
supports_id |
alias:<gdpr|eidas|nis2|cra|spid|cie|anpr|pagopa|io>, or a URN (urn_rfc2141), or a URI with scheme + host |
— |
urn_rfc2141 is go-urn's grammar, which is not exactly RFC 2141: /, ? and
# are rejected and % may be followed by any two alphanumerics (%zz).
The editor's implementation is checked value by value against the parser's
own validators by scripts/vocab/oracle (see the editor's
docs/parity-report.md). That test found that go-spdx panics on
DocumentRef-x and ( (nil token dereference): in the editor this kills the
WASM runtime until the page is reloaded.
maxLength/minLength stay standard keywords in the schema (so other tools
still get a sensible limit), but the editor's Ajv instance redefines them to
count grapheme clusters like the parser's umax/umin (uniseg).
- Errors: everything in §1–§5 except the deprecations, plus the path, extension and oEmbed checks in §6.
- Warnings (never block the editor): the version-not-latest message,
monochromeLogo,legal.authorsFile,legal.repoOwner,inputTypes,outputTypes,genericName, lowercase country codes, lowercaseit,IT.conforme,IT.riuso.codiceIPA.
| Version | Change |
|---|---|
| v5.2.2 | url on GitHub accepts trailing slashes (network check) |
| v5.3.0 | bcp47_language_tag → bcp47_strict_language_tag for availableLanguages and description keys; oEmbed providers replaced by a scheme list; v1 skeleton |
| v5.3.1 | case-insensitive urn: / x-italian-pa: in organisation_uri; minimum PNG logo width check removed |
| v5.4.0 | publiccodeYmlVersion 0.7/0.7.0; supports[*].id (supports_id); the "not latest version" warning now exempts 0.7* instead of 0.5* |
| after v5.4.3 | only the iPA code list (data/it/ipa_codes.txt) and the file name in diagnostics |