[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * JSON Schema API: shared functions for working with JSON Schema.
   4   *
   5   * @package WordPress
   6   * @subpackage JSON_Schema
   7   * @since 7.1.0
   8   */
   9  
  10  /**
  11   * Gets the JSON Schema keywords allowed for a given schema profile.
  12   *
  13   * Use the returned list to decide which keywords to keep when a schema is
  14   * output as JSON. Both profiles describe JSON Schema draft-04 output, also
  15   * called JSON Schema Version 4. They differ only in how much of the keyword
  16   * vocabulary stays in the result.
  17   *
  18   * - 'rest-api' returns the subset of draft-04 that the WordPress REST API
  19   *   uses for route output. This is the default.
  20   * - 'draft-04' returns the larger draft-04 set used when publishing a schema
  21   *   as a standalone document to clients, such as the Abilities API. It keeps
  22   *   documentation and passthrough keywords like '$ref', 'definitions',
  23   *   'allOf', 'not', 'dependencies', and 'additionalItems'.
  24   *
  25   * The keywords are allowed to stay in the schema output. This does not mean
  26   * WordPress validates or sanitizes values against them.
  27   *
  28   * @since 7.1.0
  29   *
  30   * @param string $schema_profile Optional. Name of the schema profile to get keywords for.
  31   *                               Accepts 'rest-api' or 'draft-04'. Any other value falls
  32   *                               back to the 'rest-api' profile. Default 'rest-api'.
  33   * @return string[] Allowed JSON Schema keywords.
  34   */
  35  function wp_get_json_schema_allowed_keywords( string $schema_profile = 'rest-api' ): array {
  36      $rest_keywords = rest_get_allowed_schema_keywords();
  37  
  38      $keywords_by_profile = array(
  39          'rest-api' => $rest_keywords,
  40          'draft-04' => array_merge(
  41              array(
  42                  '$schema',
  43                  'id',
  44                  '$ref',
  45              ),
  46              $rest_keywords,
  47              array(
  48                  'required',
  49                  'allOf',
  50                  'not',
  51                  'definitions',
  52                  'dependencies',
  53                  'additionalItems',
  54              )
  55          ),
  56      );
  57  
  58      $allowed_keywords = $keywords_by_profile[ $schema_profile ] ?? $rest_keywords;
  59  
  60      /**
  61       * Filters the JSON Schema keywords allowed for a given schema profile.
  62       *
  63       * Adding a keyword lets it stay in the schema output for that profile.
  64       * It does not make WordPress validate or sanitize values against the keyword.
  65       *
  66       * @since 7.1.0
  67       *
  68       * @param string[] $allowed_keywords Allowed JSON Schema keywords.
  69       * @param string   $schema_profile   The schema profile the keywords are for.
  70       */
  71      return apply_filters( 'wp_json_schema_allowed_keywords', $allowed_keywords, $schema_profile );
  72  }