XooCode(){

PropertyValueSpecification

PropertyValueSpecification describes the constraints on an Action's input or output, the same way an HTML form input constrains what a user can enter. It's how an Action's potentialAction tells a consumer "this parameter is required, must be a number between 1 and 100, defaults to 10". It surfaces in schema.org's Action model via the -input and -output hints (e.g. "query-input": "required name=q" on a SearchAction).

Full example of schema.org/PropertyValueSpecification json-ld markup

The markup is verified as valid with Rich Results Test from Google.

Highlight legend:Required by GoogleRecommendedOptional
schema.org/PropertyValueSpecification
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "WebSite",
  "name": "xoocode",
  "url": "https://xoocode.com",
  "potentialAction": {
    "@type": "SearchAction",
    "target": {
      "@type": "EntryPoint",
      "urlTemplate": "https://xoocode.com/search?q={search_term_string}"
    },
    "query-input": {
      "@type": "PropertyValueSpecification",
      "valueName": "search_term_string",
      "valueRequired": true,
      "valueMinLength": 1,
      "valueMaxLength": 200,
      "multipleValues": false,
      "readonlyValue": false
    }
  }
}
</script>

Direct properties (11)

  • valueName: parameter name referenced from URL templates and form encoding.
  • valueRequired: Boolean, must be filled in for the Action to complete.
  • readonlyValue: Boolean, the value is fixed and cannot be edited.
  • multipleValues: Boolean, the parameter accepts an array of values.
  • defaultValue: pre-filled value (literal or Thing).
  • valuePattern: regex (HTML-spec style) for literal validation.
  • valueMinLength / valueMaxLength: integer character bounds for text.
  • minValue / maxValue: numeric range for numbers and dates.
  • stepValue: granularity for numeric inputs (1, 0.01, 60).

When to use

PropertyValueSpecification is almost always attached via the -input / -output token on an Action property. For a SearchAction you'd write "query-input": "required maxlength=100 name=q" as a compact string, or spell it out as a PropertyValueSpecification node. The full object form is more discoverable for AI agents and validators.

Minimal valid version

The smallest markup that still produces a valid PropertyValueSpecification entity. Use it as the floor. Reach for the advanced example above when you want search engines and AI agents to understand more about your content.

schema.org/PropertyValueSpecification (minimal)
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "PropertyValueSpecification",
  "valueName": "q",
  "valueRequired": true,
  "valueMaxLength": 100
}
</script>

Google rich results this unlocks

Markup matching this example makes your page eligible for the following Google Search rich results. The primary target drives the required / recommended property classification in the advanced code block above.

  • Sitelinks search box (via containing SearchAction)primary
    Google docs

Common PropertyValueSpecification mistakes

Mistakes that pass validation but silently fail to earn rich results or mislead consumers walking the graph. Avoid these and your markup will be ahead of most sites in the wild.

  1. 01

    Shorthand string + object both given

    Wrong
    Both "query-input": "required name=q" and a PropertyValueSpecification node
    Right
    Pick one form; mixed forms confuse some parsers

    Google accepts either the compact `-input` token string or the full object; keep the form consistent.

  2. 02

    valueRequired as "true"

    Wrong
    "valueRequired": "true"
    Right
    "valueRequired": true

    Boolean, not string. Validators reject the stringified form.

  3. 03

    Pattern with slash delimiters

    Wrong
    "valuePattern": "/^[a-z]+$/"
    Right
    "valuePattern": "^[a-z]+$"

    The regex is the raw expression (HTML spec form). No slashes, no flags.

Schema properties in this example

PropertyValueSpecificationIntangibleWebSitepotentialActionSearchActiontargetEntryPointurlTemplatequery-inputvalueNamevalueRequiredvalueMinLengthvalueMaxLengthmultipleValuesreadonlyValuedefaultValueminValuemaxValuestepValuevaluePattern

About the example data

The search action on xoocode.com described with PropertyValueSpecification: required query, 1–200 characters, no pattern restriction.

Comments

Loading comments...

Leave a comment