Custom Entity Schemas in ShotGrid: Tailoring Pipelines Without Code

Problem: Studio‑Specific Data in a Generic Tool

ShotGrid ships with a set of core entities – Asset, Shot, Task, etc. – that cover most production workflows. In practice, studios often need to track extra data that doesn’t fit the out‑of‑the‑box schema: a character’s voice actor, a shot’s story beat, or a specific camera rig. Adding this data by hand to the database or writing custom scripts can become brittle and hard to maintain.

The question is: can we extend ShotGrid’s data model without touching code or creating a custom database layer?

Thesis: Use Custom Entity Schemas to Add Fields, Enforce Rules, and Expose API Endpoints

ShotGrid’s Custom Entity Schema feature lets administrators create new fields on any entity and define their type, default value, visibility, and validation rules. Once a field is published, ShotGrid automatically updates its web UI, the REST API, and any third‑party integrations that rely on the schema. This means you can tailor your pipeline to studio‑specific needs while keeping everything under ShotGrid’s governance.

Step‑by‑Step: Adding a “Story Beat” List Field to Shots

1. Navigate to the Schema UI

   Login to your ShotGrid site with an administrator account. Click Admin → Entity Schema. Select Shot from the dropdown.

2. Create the Field

   Click Add Field. Enter the following details:

   • Label: Story Beat
   • API Name: story_beat (auto‑generated but can be edited)
   • Field Type: List
   • Options: Opening, Development, Climax, Resolution
   • Required: No (you may want to enforce it later)
   • Visibility: Public (visible to all users)
   Click Save.

3. Publish the Schema

   In the top right, click Publish. ShotGrid will validate the changes and, if no conflicts, make the new field live. All existing Shot forms now show a dropdown for Story Beat.

4. Verify in the Web UI

   Create a new Shot via the web UI. The Story Beat field appears in the form. Select Climax and save. Open the Shot again to confirm the value persists.

5. Query via the REST API

   Use the GET /api/v1/entity/Shot?filter=[...] endpoint to retrieve the field. Example using curl:

   curl -H "Authorization: Bearer <API_TOKEN>" \
        -H "Content-Type: application/json" \
        "https://<YOUR_SITE>.shotgrid.net/api/v1/entity/Shot?filter=[{"field":"story_beat","operator":"equals","value":"Climax"}]"
   

   The JSON response will include story_beat: "Climax".

6. Use shotgrid3 to Create and Read a Shot

   Python example:

   from shotgrid_api import ShotGrid
   
   sg = ShotGrid(base_url="https://<YOUR_SITE>.shotgrid.net", project_id=<PROJECT_ID>, api_key=<API_KEY>)
   
   # Create a Shot with the new field
   shot = sg.create("Shot", {"name": "TestShot01", "code": "TS01", "story_beat": "Opening"})
   print(f"Created Shot ID: {shot.id}")
   
   # Query back
   shots = sg.find("Shot", filter=[{"field": "story_beat", "operator": "equals", "value": "Opening"}])
   for s in shots:
       print(f"{s.name} - Beat: {s.story_beat}")
   

   Running this script confirms the field is stored and retrievable.

Trade‑Offs and Limitations

• Performance: Adding many complex fields (e.g., large lists or entity references) can increase query times, especially on large datasets. Test in a sandbox before publishing to production.
• Compatibility: Existing reports, dashboards, or custom scripts that reference field names must be updated after a schema change. ShotGrid preserves the old field ID, but the API name may change if you rename a field.
• Visibility Rules: While you can hide fields from certain roles, the UI still renders them; consider using permissions to protect sensitive data.
• Versioning: Each schema change is versioned. You can roll back to a previous version if a change breaks downstream processes, but you must also adjust any dependent scripts.

Actionable Takeaway

1. Plan your schema changes in a sandbox project. Use the Preview mode in the Entity Schema UI to see how the new fields will appear.

2. Publish incrementally. Add one field at a time, test the UI, API, and any automated scripts.

3. Update downstream code (Python scripts, ETL jobs, dashboards) to reference the new API names. Use the sg.find method to discover field IDs if needed.

4. Monitor performance after publishing. If query times spike, consider simplifying the field type or moving heavy data to an external system.

By leveraging ShotGrid’s Custom Entity Schema, studios can keep their pipelines flexible, enforce data consistency, and avoid the maintenance overhead of custom databases or ad‑hoc scripts.