From 14eb58ebba7ba7b6bd3a61a140d183a76a547d3d Mon Sep 17 00:00:00 2001 From: Clemens Vasters Date: Mon, 8 Jun 2026 11:46:20 +0200 Subject: [PATCH] Clarify roles of patternProperties/patternKeys vs propertyNames/keyNames - patternProperties validates property VALUES based on name patterns; explicitly note it does not define or declare properties - propertyNames validates property NAMES themselves against a schema - Distinguish the two clearly so readers understand when to use which Fixes #1 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- draft-vasters-json-structure-validation.md | 22 ++++++++++++++-------- 1 file changed, 14 insertions(+), 8 deletions(-) diff --git a/draft-vasters-json-structure-validation.md b/draft-vasters-json-structure-validation.md index c7e89e8..090e7d4 100644 --- a/draft-vasters-json-structure-validation.md +++ b/draft-vasters-json-structure-validation.md @@ -364,10 +364,14 @@ Example: ### `patternProperties` and `patternKeys` {#patternProperties-and-patternKeys} -This keyword applies schemas to properties whose names match specified regular -expressions. For each property in the object instance, if its name matches a -regular expression defined in `patternProperties`, then its value MUST validate -against the corresponding schema. The property names used as keys in +This keyword applies validation schemas to the **values** of properties whose +names match specified regular expressions. It does not define or declare +properties; rather, it constrains the values of any properties that happen to +match the given patterns. + +For each property in the object instance, if its name matches a regular +expression defined in `patternProperties`, then its value MUST validate against +the corresponding schema. The property names used as keys in `patternProperties` MUST be strings representing valid regular expressions conforming to the {{ECMA_262_2022}} standard. The `patternKeys` keyword applies equivalently to `map` types. @@ -389,10 +393,12 @@ Example: ### `propertyNames` and `keyNames` {#propertyNames-and-keyNames} -The `propertyNames` keyword validates the names of all properties in an object -against a `string`-typed schema. An object is valid if every property name in -the object is valid. The schema MUST be of type `string`. The `keyNames` keyword -applies equivalently to `map` types. +The `propertyNames` keyword constrains the **names** of all properties in an +object. Unlike `patternProperties`, which validates property values based on +name patterns, `propertyNames` validates the names themselves against a +`string`-typed schema. An object is valid only if every property name in the +object satisfies the given schema. The schema MUST be of type `string`. The +`keyNames` keyword applies equivalently to `map` types. Example: