Create an aspect

Create and deploy aspects for Media Library.

Aspects are sets of properties that describe an asset and are defined just like schemas. Asset managers can apply aspects to assets in the library, with mutations, or programmatically during upload. This information stored in aspects is specific to the Media Library. For local metadata, you should use fields in your Studio projects.

In this guide, you'll create a new aspect and deploy it to your Media Library.

Prerequisites:

• sanity v3.85.1 or higher

In a project with a sanity.cli.ts file, edit the configuration to include a mediaLibrary.aspectsPath.

import {defineCliConfig} from 'sanity/cli'

export default defineCliConfig({
  api: {
    projectId: '3do82whm',
    dataset: 'production'
  },
  mediaLibrary: {
    aspectsPath: 'aspects',
  },
  autoUpdates: true,
})

In the example above, the aspects directory is relative to the location of the sanity.cli.ts file.

In the same directory, generate a new aspect with the Sanity CLI.

sanity media create-aspect

This command prompts you for a name and creates a new aspect in your project. Aspect names must be unique and contain only letters, numbers, and hyphens.

Aspects can be a single field or an object containing multiple fields. They can contain strings, objects, arrays, or nearly any Studio schema type.

The CLI creates an object-type aspect with a single string field similar to the example below. In this case, we set the name as copyright.

import {defineAssetAspect, defineField} from 'sanity'

export default defineAssetAspect({
  name: 'copyright',
  title: 'copyright',
  type: 'object',
  fields: [
    defineField({
      name: 'string',
      title: 'Plain String',
      type: 'string',
    }),
  ],
})

Modify the aspect with more fields. In this example, we'll update the existing string field and add a date type field.

import {defineAssetAspect, defineField} from 'sanity'

export default defineAssetAspect({
  name: 'copyright',
  title: 'copyright',
  type: 'object',
  fields: [
    defineField({
      name: 'copyrightHolder',
      title: 'Copyright Holder',
      type: 'string',
    }),
    defineField({
      name: 'copyrightDate',
      title: 'Date',
      type: 'date',
    }),
  ],
})

Once deployed, this will look like the following in your Media Library:

You can see more aspect examples in the aspect patterns cheat sheet.

If you want to easily query the aspect value from your dataset, unauthenticated, you can mark the aspect as public:

import {defineAssetAspect, defineField} from 'sanity'

export default defineAssetAspect({
  name: 'copyright',
  title: 'copyright',
  type: 'object',
  fields: [
    defineField({
      name: 'copyrightHolder',
      title: 'Copyright Holder',
      type: 'string',
    }),
    defineField({
      name: 'copyrightDate',
      title: 'Date',
      type: 'date',
    }),
  ],
  public: true
})

When the aspect definition is marked as public you can then resolve the value from your dataset by using media::aspect(MEDIA_REF, "ASPECT"):

*[_type == "post"] {
  _id,
  title,
  mainImage {
    asset,
    "copyright": media::aspect(media, "copyright")
  }
}

With your aspect defined, it's time to deploy it to your Media Library.

Run the following to deploy a single aspect. Replace copyright with your aspect name.

sanity media deploy-aspect copyright

If you make additional changes to the aspect, you can update it by running the deploy-aspect command again.

To delete an aspect from your library, run the following command, replacing copyright with the name of your aspect.

sanity media delete-aspect copyright

This deletes the aspect from your Library, but will not remove the local definition file.