/ 
Dist-Conformance-0.001
/ Dist::Conformance::Schema

NAME

Dist::Conformance::Schema - Parse YAML and JSON, and validate the result against a schema

VERSION

version 0.001

SYNOPSIS

use 5.040;
use Dist::Conformance::Schema;

my $data = Dist::Conformance::Schema::parse_yaml( "name: troglodyne\n", 'conformance/troglodyne.yml' );
$data = Dist::Conformance::Schema::validate(
    $data,
    { type => 'object', required => ['name'], properties => { name => $Dist::Conformance::Schema::NAME } },
    'conformance/troglodyne.yml',
);

DESCRIPTION

Every file that Dist::Conformance reads is data that somebody wrote by hand: a flavor file, .conformance.yml, the configuration of a check. This module holds the two things that each of them needs: a parser whose error names the file, and a validator whose errors name the file and the key.

The schemas are OpenAPI v3 schemas for JSON::Validator::Schema::Troglodyne. That means nullable instead of a type list, and no propertyNames. The validator fills in the default of each key that the data leaves out, and coerces true, false, yes, no, 1, 0 and the empty string to a boolean where the schema asks for one.

FUNCTIONS

parse_yaml

($text, $where). Returns the mapping that the YAML document $text holds. Dies with a message that starts with $where when the text does not parse, or when its top level is not a mapping.

parse_json

($bytes, $where). The same as "parse_yaml", for UTF-8 JSON text.

encode_json

($data). Returns $data as UTF-8 JSON, indented by two spaces, with the keys sorted, and with a final newline, so that a file that this distribution writes gives a small diff the next time it changes.

validate

($data, $schema, $where). Returns a copy of $data with the defaults of $schema filled in. Dies when the data does not match: the message starts with $where is not valid:, and then gives each error on a line of its own, as the JSON pointer of the key and what is wrong with it, such as /checks/ClaudeMd/file: Expected string - got array. The caller's data is not changed.

errors

($data, $schema). The errors of $data against $schema, each as a string that starts with the JSON pointer of its key, or none. Fills in the defaults of $schema in $data, and coerces its booleans, in place.

matches

($fragment, $value). Whether $value is defined and matches the pattern of $fragment, such as "$NAME", in the way that JSON::Validator matches it.

relative_path

($path, $inside). Returns $path when it matches "$PATH". Otherwise dies with $path is not a relative path inside $inside. Every read and write of a path that a flavor names goes through it.

first_line

($text). The first line of an error from other code, without the "at FILE line N" that perl adds to it, for a message that is about a file of the user and not about a line of this code. The errors of this distribution end in a newline, so perl adds nothing to them.

SCHEMA FRAGMENTS

These package variables are pieces that the schemas of this distribution share. A check module can use them in its own config_schema.

$NAME

A name of a flavor or a check: a letter or digit, then letters, digits, ., _ or -. A name never holds a /, so it can be a file name.

$PATH

A relative path inside a repository or a standards source: not absolute, and with no .. component.

$STATUS

pass, info or fail.

SEE ALSO

Please see those modules/websites for more information related to this module.

BUGS

Please report any bugs or feature requests on the bugtracker website https://github.com/Troglodyne-Internet-Widgets/Dist-Conformance/issues

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

AUTHORS

Current Maintainers:

  • George S. Baugh <george@troglodyne.net>

COPYRIGHT AND LICENSE

Copyright (c) 2026 Troglodyne LLC

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.