docs: document custom keyword validation

[levenleven]

Add an example how to extend vocab and error on deprecated fields.

[davishmcclurg]

Hi @levenleven, I appreciate the contribution. I don't think I want to formally encourage this form of vocabulary extension, though. JSONSchemer::Draft202012::Vocab::VALIDATION isn't really meant to be exposed to users.

In the future, I'd like to introduce custom keyword support through somehow registering custom vocabularies, similar to the built-in vocabularies here:

json_schemer/lib/json_schemer.rb

Lines 79 to 102 in da9c8f9

	VOCABULARIES = {
	'https://json-schema.org/draft/2020-12/vocab/core' => Draft202012::Vocab::CORE,
	'https://json-schema.org/draft/2020-12/vocab/applicator' => Draft202012::Vocab::APPLICATOR,
	'https://json-schema.org/draft/2020-12/vocab/unevaluated' => Draft202012::Vocab::UNEVALUATED,
	'https://json-schema.org/draft/2020-12/vocab/validation' => Draft202012::Vocab::VALIDATION,
	'https://json-schema.org/draft/2020-12/vocab/format-annotation' => Draft202012::Vocab::FORMAT_ANNOTATION,
	'https://json-schema.org/draft/2020-12/vocab/format-assertion' => Draft202012::Vocab::FORMAT_ASSERTION,
	'https://json-schema.org/draft/2020-12/vocab/content' => Draft202012::Vocab::CONTENT,
	'https://json-schema.org/draft/2020-12/vocab/meta-data' => Draft202012::Vocab::META_DATA,
	'https://json-schema.org/draft/2019-09/vocab/core' => Draft201909::Vocab::CORE,
	'https://json-schema.org/draft/2019-09/vocab/applicator' => Draft201909::Vocab::APPLICATOR,
	'https://json-schema.org/draft/2019-09/vocab/validation' => Draft201909::Vocab::VALIDATION,
	'https://json-schema.org/draft/2019-09/vocab/format' => Draft201909::Vocab::FORMAT,
	'https://json-schema.org/draft/2019-09/vocab/content' => Draft201909::Vocab::CONTENT,
	'https://json-schema.org/draft/2019-09/vocab/meta-data' => Draft201909::Vocab::META_DATA,
	'json-schemer://draft7' => Draft7::Vocab::ALL,
	'json-schemer://draft6' => Draft6::Vocab::ALL,
	'json-schemer://draft4' => Draft4::Vocab::ALL,
	'https://spec.openapis.org/oas/3.1/vocab/base' => OpenAPI31::Vocab::BASE,
	'json-schemer://openapi30' => OpenAPI30::Vocab::BASE
	}

Then meta schemas would need to specify them by name in $vocabulary, eg:

json_schemer/lib/json_schemer/draft202012/meta.rb

Lines 35 to 43 in da9c8f9

	'$vocabulary' => {
	'https://json-schema.org/draft/2020-12/vocab/core' => true,
	'https://json-schema.org/draft/2020-12/vocab/applicator' => true,
	'https://json-schema.org/draft/2020-12/vocab/unevaluated' => true,
	'https://json-schema.org/draft/2020-12/vocab/validation' => true,
	'https://json-schema.org/draft/2020-12/vocab/meta-data' => true,
	'https://json-schema.org/draft/2020-12/vocab/format-annotation' => true,
	'https://json-schema.org/draft/2020-12/vocab/content' => true
	},

I believe that matches the intention in the spec. Unfortunately, right now there isn't a way to add custom keywords that I feel comfortable documenting. Thanks again for taking the time to write this up. Let me know if you want to help out with a custom keyword/vocabulary implementation.