Add a standardised way to register post meta and REST fields

[darylldoyle]

Is your enhancement related to a problem? Please describe.

Coming out of 10up/wp-scaffold#218 @nicholasio asked the following:

Could we add a more structured way for registering custom fields? I'd love to use register_rest_field and/register_meta registering custom fields in this way where you also declare the "schema" makes things easier for headless projects. I'm thinking mostly from a REST API standpoint and not really thinking about us creating a wrapper around rendering the custom fields in the editor.

The end goal here is to make sure we're consistent in how we are exposing custom fields through the REST API. There are lots of ways to do it and it doesn't always get added to the REST API schema.

See this for example: https://github.com/10up/headstartwp/blob/develop/wp/headless-wp/includes/classes/Preview/PreviewLink.php#L36

This is a great opportunity to look at providing a better way to register post meta within the scaffold.

Whatever we provide must be easy-to-use, whilst being flexible for those who need to utilize all options.

This issue is here to discuss approaches before any implementation happens.

[claytoncollie]

@darylldoyle Can this be closed?

[darylldoyle]

@claytoncollie we haven't handled this side of things yet, so I think we should leave it open for now.

[fabiankaegy]

@darylldoyle just closing the loop here. In slack the two of us chatted a bit more about this recently and @darylldoyle suggested an API somewhat like this:

register_post_meta('post', 'note', [
  'type'         => 'string',
  'single'       => true,
  'show_in_rest' => Meta_Rest_Schemas::string(),
]);

register_post_meta('post', 'settings', [
  'type'         => 'object',
  'single'       => true,
  'show_in_rest' => Meta_Rest_Schemas::new()
    ->object([
      'enabled' => [ 'type' => 'boolean' ],
      'label'   => [ 'type' => 'string' ],
    ])
    ->required(['enabled'])
    ->additional_properties(false)
    ->build(),
]);

$item = Meta_Rest_Schemas::new()
  ->object([
    'id'   => [ 'type' => 'integer' ],
    'text' => [ 'type' => 'string' ],
    'done' => [ 'type' => 'boolean' ],
  ])
  ->required(['id','text','done'])
  ->additional_properties(false)
  ->build();

register_post_meta('post', 'checklist', [
  'type'         => 'array',
  'single'       => true,
  'show_in_rest' => Meta_Rest_Schemas::new()
    ->array_of($item)
    ->build(),
]);

Essentially having a new MetaSchemas class that allows easy creation of schemas to go alongside newly registered meta fields to ensure we have properly typed rest api endpoints :)

CC: @claytoncollie