@takeshape/schema 11.52.0 → 11.56.1

package/dist/index.js

@@ -0,0 +1,46 @@
+export * from "./content-schema-transform.js";
+export * from "./get-is-leaf.js";
+export * from "./project-schema/index.js";
+export * from "./project-schema/migrate.js";
+export * from "./schema-util.js";
+export * from "./template-shapes/index.js";
+export * from "./taxonomies.js";
+export * from "./workflows.js";
+export * from "./api-version.js";
+export * from "./migration/index.js";
+export * from "./validate/validate.js";
+export * from "./validate/errors.js";
+export * from "./builtin-schema.js";
+export * from "./versions.js";
+export * from "./mocks.js";
+export * from "./scalars.js";
+export * from "./refs.js";
+export * from "./unions.js";
+export * from "./enum.js";
+export * from "./patterns.js";
+export * from "./types/transforms.js";
+export * from "./types/types.js";
+export * from "./types/utils.js";
+export * from "./flatten-templates.js";
+export * from "./relationships.js";
+export * from "./create-input-schema.js";
+export * from "./schema-transform.js";
+export * from "./interfaces.js";
+export * from "./agents.js";
+export * from "./services/services.js";
+export * from "./services/util.js";
+export * from "./services/types.js";
+export * from "./util/api-indexing.js";
+export * from "./util/form-config.js";
+export * from "./util/ai-tools.js";
+export * from "./util/detect-cycles.js";
+export * from "./util/find-shape-at-path.js";
+export * from "./util/get-conflicting-properties.js";
+export * from "./util/get-return-shape.js";
+export * from "./util/has-arg.js";
+export * from "./util/merge.js";
+export * from "./util/patch-schema.js";
+export * from "./util/shapes.js";
+export * from "./constants.js";
+export * from "./runtime-schema.js";
+export * from "./service-dependencies.js";

package/dist/interfaces.d.ts

@@ -0,0 +1,12 @@
+import type { OneOfSchema, ProjectSchemaJSON, PropertySchema, ShapeJSON, ShapeMap } from './project-schema/index.ts';
+import type { RefItem, ServicesShapesContext } from './refs.ts';
+export declare function isInterfaceShape(shape?: ShapeJSON): boolean;
+export type ImplementationShapeMap = Record<string, Set<ShapeJSON>>;
+export type ImplementationShapeNameMap = Record<string, Set<string>>;
+export declare function isInterfaceRef(context: ServicesShapesContext, propertySchema: PropertySchema): boolean;
+export declare function getImplementationShapeMap(shapeMap: ShapeMap): ImplementationShapeMap;
+export declare function getImplementationShapeNameMap(shapeMap: ShapeMap): ImplementationShapeNameMap;
+export declare function pruneUnusedInterfaces(projectSchema: ProjectSchemaJSON, shapeMap: ShapeMap): ShapeMap;
+export declare function getImplementingShapes(context: Pick<ProjectSchemaJSON, 'services' | 'shapes'>, interfaceRef: RefItem): ShapeJSON[];
+export declare function interfaceToUnion(context: Pick<ProjectSchemaJSON, 'shapes' | 'services'>, interfaceRef: RefItem): OneOfSchema;
+export declare function getPossibleShapeNames(projectSchema: ProjectSchemaJSON, shape: ShapeJSON): string[];

package/dist/interfaces.js

@@ -0,0 +1,85 @@
+import { isDefined } from '@takeshape/util';
+import mapValues from 'lodash/mapValues.js';
+import { getRef, normalizeRefExpression, refExpressionToRefItem, refItemToNamespacedShapeName, refItemToShape, shapeToRefItem } from "./refs.js";
+import { isUnionSchema } from "./unions.js";
+export function isInterfaceShape(shape) {
+    return shape?.type === 'interface';
+}
+export function isInterfaceRef(context, propertySchema) {
+    const ref = getRef(context, propertySchema);
+    return Boolean(ref && isInterfaceShape(refItemToShape(context, ref)));
+}
+function add(record, key, value) {
+    if (!record[key]) {
+        record[key] = new Set([value]);
+    }
+    else {
+        record[key].add(value);
+    }
+}
+function getImplementationsHelper(shapeMap, mapFn) {
+    const result = {};
+    for (const shape of Object.values(shapeMap)) {
+        for (const interfaceName of shape.interfaces ?? []) {
+            add(result, interfaceName, mapFn(shape));
+        }
+    }
+    return result;
+}
+export function getImplementationShapeMap(shapeMap) {
+    return getImplementationsHelper(shapeMap, (x) => x);
+}
+export function getImplementationShapeNameMap(shapeMap) {
+    return getImplementationsHelper(shapeMap, (shape) => shape.name);
+}
+export function pruneUnusedInterfaces(projectSchema, shapeMap) {
+    return mapValues(shapeMap, (shape) => {
+        const { interfaces } = shape;
+        if (interfaces?.length) {
+            const filteredInterfaces = interfaces.filter((refExpression) => shapeMap[refItemToNamespacedShapeName(refExpressionToRefItem(projectSchema, refExpression))]);
+            if (interfaces.length !== filteredInterfaces.length) {
+                return { ...shape, interfaces: filteredInterfaces };
+            }
+        }
+        return shape;
+    });
+}
+function compareRefItems(refItem1, refItem2) {
+    return refItem1.typeName === refItem2.typeName && refItem1.serviceKey === refItem2.serviceKey;
+}
+export function getImplementingShapes(context, interfaceRef) {
+    const shapeMap = context.shapes;
+    const implementingShapes = [];
+    for (const shape of Object.values(shapeMap)) {
+        if (shape.interfaces?.find((interfaceRefExpression) => compareRefItems(refExpressionToRefItem(context, interfaceRefExpression), interfaceRef))) {
+            implementingShapes.push(shape);
+        }
+    }
+    return implementingShapes;
+}
+export function interfaceToUnion(context, interfaceRef) {
+    const shapes = getImplementingShapes(context, interfaceRef);
+    return {
+        oneOf: shapes.map((shape) => ({
+            '@ref': normalizeRefExpression(context, shape.name)
+        }))
+    };
+}
+export function getPossibleShapeNames(projectSchema, shape) {
+    let names;
+    if (isInterfaceShape(shape)) {
+        names = getImplementingShapes(projectSchema, shapeToRefItem(projectSchema, shape)).map((shape) => shape.name);
+    }
+    else if (isUnionSchema(shape.schema)) {
+        names = shape.schema.oneOf
+            .map((member) => {
+            const ref = getRef(projectSchema, member);
+            return ref && refItemToNamespacedShapeName(ref);
+        })
+            .filter(isDefined);
+    }
+    else {
+        names = [shape.name];
+    }
+    return names;
+}

package/dist/layers/__tests__/layers.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/layers/__tests__/layers.test.js

@@ -0,0 +1,38 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { expect, test } from 'vitest';
+import { flattenSchema } from "../layers.js";
+function loadFile(fileName) {
+    return JSON.parse(fs.readFileSync(fileName, 'utf8'));
+}
+function getPath(...filePath) {
+    return path.join(__dirname, '..', '..', '..', 'examples', 'v4_0_0', ...filePath);
+}
+const layerCache = new Map();
+const getLayer = (exampleName) => (layerId) => {
+    const layerPath = getPath(exampleName, 'layers', `${layerId}.json`);
+    let layer = layerCache.get(layerPath);
+    if (!layer) {
+        layer = loadFile(layerPath);
+        layerCache.set(layerPath, layer);
+    }
+    return layer;
+};
+function getSchema(exampleName) {
+    return loadFile(getPath(exampleName, 'schema.json'));
+}
+function getFlattenedSchema(exampleName) {
+    return loadFile(getPath(exampleName, 'flattened-schema.json'));
+}
+test.skip('flattenSchema - rick-and-morty-notes', () => {
+    const exampleName = 'rick-and-morty-notes';
+    const schema = getSchema(exampleName);
+    const flattened = flattenSchema(schema, getLayer(exampleName));
+    expect(flattened).toEqual(getFlattenedSchema(exampleName));
+});
+test.skip('flattenSchema - shopify-lookbook', () => {
+    const exampleName = 'shopify-lookbook';
+    const schema = getSchema(exampleName);
+    const flattened = flattenSchema(schema, getLayer(exampleName));
+    expect(flattened).toEqual(getFlattenedSchema(exampleName));
+});

package/dist/layers/layers.d.ts

@@ -0,0 +1,26 @@
+import type { FlattenedSchemaV4_0_0, LayerSchemaV4_0_0, ObjectSchemaV4_0_0, ProjectSchemaJSONV4_0_0, PropertySchemaV4_0_0, QueryJSONV4_0_0, ShapeMapV4_0_0 } from '../project-schema/index.ts';
+import { type RefItemWithPath } from './refs.ts';
+export type GetLayer = (layerId: string) => LayerSchemaV4_0_0 | undefined;
+export declare function isObjectSchemaV4_0_0(maybeObjectSchema: PropertySchemaV4_0_0): maybeObjectSchema is ObjectSchemaV4_0_0;
+export type RefPredicate = (ref: RefItemWithPath) => boolean;
+/**
+ * Walk through a `ProjectSchema` and collect all the `ref`s.
+ */
+export declare function getAllRefsInShapes(shapes: ShapeMapV4_0_0, predicate?: RefPredicate): RefItemWithPath[];
+/**
+ * Get all refs
+ */
+export declare function getAllRefsInQuery(shapes: ShapeMapV4_0_0, queryPath: string[], query: QueryJSONV4_0_0, predicate?: (ref: RefItemWithPath) => boolean): RefItemWithPath[];
+type SchemaContext = Pick<FlattenedSchemaV4_0_0, 'shapes' | 'queries' | 'mutations'>;
+/**
+ * Collect refs from `queries` or `mutations`.
+ */
+export declare function getAllRefsInQueries(context: SchemaContext, rootPropertyName: 'queries' | 'mutations', predicate?: RefPredicate): RefItemWithPath[];
+/**
+ * Get all refs in a ProjectSchema
+ * @param predicate return true to include the ref in
+ */
+export declare function getAllRefs(projectSchema: SchemaContext, predicate?: RefPredicate): RefItemWithPath[];
+export declare function collectReferencedShapeNames(layerId: string, refSet: Set<string>): (schema: PropertySchemaV4_0_0) => void;
+export declare function flattenSchema(projectSchema: ProjectSchemaJSONV4_0_0, getLayer: GetLayer): FlattenedSchemaV4_0_0;
+export {};

package/dist/layers/layers.js

@@ -0,0 +1,301 @@
+import { deepClone, isDefined, isRecord } from '@takeshape/util';
+import set from 'lodash/set.js';
+import uniq from 'lodash/uniq.js';
+import minimatch from 'minimatch';
+import { parseTemplateShape } from "../refs.js";
+import { dereferenceSchema, getArgsReferenceWithPath, getRefOrItemsRef, parseReturnShape, refItemToString, splitAtRef } from "./refs.js";
+import { isAllOfSchema, isObjectSchema, isOneOfSchema, isRefSchema } from "./type-utils.js";
+import { visitSchemaProperties } from "./visitor.js";
+const layerDefaults = {
+    namespace: '',
+    visibility: []
+};
+function filterMap(prefix, fields, filters) {
+    const result = {};
+    for (const [name, value] of Object.entries(fields)) {
+        for (const filter of filters) {
+            if (minimatch(`${prefix}.${name}`, filter)) {
+                result[name] = value;
+            }
+        }
+    }
+    return result;
+}
+function filterLayer(layerSchema, filters) {
+    return {
+        ...layerSchema,
+        queries: filterMap('queries', layerSchema.queries ?? {}, filters),
+        mutations: filterMap('mutations', layerSchema.mutations ?? {}, filters),
+        shapes: filterMap('shapes', layerSchema.shapes ?? {}, filters),
+        workflows: filterMap('workflows', layerSchema.workflows ?? {}, filters)
+    };
+}
+// TODO use non-versioned util eventually
+export function isObjectSchemaV4_0_0(maybeObjectSchema) {
+    return maybeObjectSchema.type === 'object' && isRecord(maybeObjectSchema.properties);
+}
+function mergeShape(a, b) {
+    if (b.override === 'extend') {
+        if (isObjectSchemaV4_0_0(a.schema) && isObjectSchemaV4_0_0(b.schema)) {
+            const combinedRequired = uniq((a.schema.required ?? []).concat(b.schema.required ?? []));
+            const combinedSchema = {
+                type: 'object',
+                properties: {
+                    ...a.schema.properties,
+                    ...b.schema.properties
+                }
+            };
+            if (combinedRequired.length) {
+                combinedSchema.required = combinedRequired;
+            }
+            return { ...a, ...b, schema: combinedSchema };
+        }
+    }
+    return b;
+}
+function assignShapes(flattenedShapes, layerShapes) {
+    for (const [shapeName, shape] of Object.entries(layerShapes)) {
+        flattenedShapes[shapeName] = flattenedShapes[shapeName] ? mergeShape(flattenedShapes[shapeName], shape) : shape;
+    }
+}
+function addRef(refs, ref, predicate) {
+    if (ref && (!predicate || predicate(ref))) {
+        refs.push(ref);
+    }
+}
+/**
+ * Walk through a `ProjectSchema` and collect all the `ref`s.
+ */
+export function getAllRefsInShapes(shapes, predicate) {
+    const items = [];
+    const shapeVisitor = (schema, schemaPath) => {
+        if (schema['@args'] && typeof schema['@args'] === 'object') {
+            visitSchemaProperties(schema['@args'], schemaPath.concat(['@args']), (argSchema, argPath) => {
+                addRef(items, getRefOrItemsRef(argSchema, argPath), predicate);
+            });
+        }
+        addRef(items, getArgsReferenceWithPath(schema, schemaPath), predicate);
+        const newPath = schema.items ? schemaPath.concat('items') : schemaPath;
+        const newSchema = schema.items ?? schema;
+        if (isRefSchema(newSchema)) {
+            addRef(items, getRefOrItemsRef(newSchema, newPath), predicate);
+        }
+        else if (isObjectSchema(newSchema) || isAllOfSchema(newSchema) || isOneOfSchema(newSchema)) {
+            visitSchemaProperties(newSchema, newPath, shapeVisitor);
+        }
+    };
+    for (const [shapeName, shape] of Object.entries(shapes)) {
+        visitSchemaProperties(shape.schema, ['shapes', shapeName, 'schema'], shapeVisitor);
+    }
+    return items;
+}
+/**
+ * Get all refs
+ */
+export function getAllRefsInQuery(shapes, queryPath, query, predicate) {
+    const refItems = [];
+    const propertyVisitor = (propSchema, propSchemaPath) => {
+        addRef(refItems, getRefOrItemsRef(propSchema, propSchemaPath), predicate);
+    };
+    if (query.args && typeof query.args === 'string') {
+        addRef(refItems, getArgsReferenceWithPath(query, queryPath), predicate);
+    }
+    if (query.args && typeof query.args === 'object') {
+        visitSchemaProperties(dereferenceSchema(shapes, query.args), queryPath, propertyVisitor);
+    }
+    if (query.shape) {
+        const refItem = parseReturnShape(query.shape).ref;
+        if (refItem) {
+            addRef(refItems, {
+                ...refItem,
+                path: queryPath.concat(['shape'])
+            }, predicate);
+        }
+    }
+    return refItems;
+}
+/**
+ * Collect refs from `queries` or `mutations`.
+ */
+export function getAllRefsInQueries(context, rootPropertyName, predicate) {
+    const refItems = [];
+    const rootPath = [rootPropertyName];
+    for (const [queryName, query] of Object.entries(context[rootPropertyName])) {
+        const queryPath = rootPath.concat([queryName]);
+        const queryRefs = getAllRefsInQuery(context.shapes, queryPath, query, predicate);
+        if (queryRefs.length) {
+            refItems.push(...queryRefs);
+        }
+    }
+    return refItems;
+}
+/**
+ * Get all refs in a ProjectSchema
+ * @param predicate return true to include the ref in
+ */
+export function getAllRefs(projectSchema, predicate) {
+    return [
+        ...getAllRefsInShapes(projectSchema.shapes, predicate),
+        ...getAllRefsInQueries(projectSchema, 'queries', predicate),
+        ...getAllRefsInQueries(projectSchema, 'mutations', predicate)
+    ];
+}
+export function collectReferencedShapeNames(layerId, refSet) {
+    const addLayerId = (ref) => ({ ...ref, layerId });
+    const collect = (schema) => {
+        const args = schema['@args'];
+        if (args && typeof args === 'object') {
+            Object.values(args.properties).forEach(collect);
+        }
+        const argsRefItem = getArgsReferenceWithPath(schema);
+        if (argsRefItem) {
+            refSet.add(refItemToString(addLayerId(argsRefItem)));
+        }
+        const refItem = getRefOrItemsRef(schema);
+        if (refItem) {
+            refSet.add(refItemToString(addLayerId(refItem)));
+        }
+    };
+    return collect;
+}
+function collectServiceRefs(flattenedSchema, getLayer) {
+    const refs = new Set(getAllRefs(flattenedSchema, (refItem) => refItem.layerId !== 'local').map(refItemToString));
+    if (refs.size) {
+        for (const ref of refs) {
+            const [layerId, shapeName] = splitAtRef(ref);
+            if (layerId !== 'local') {
+                const layer = getLayer(layerId);
+                const shape = layer?.shapes?.[shapeName];
+                if (shape) {
+                    visitSchemaProperties(shape.schema, ['schema'], collectReferencedShapeNames(layerId, refs));
+                }
+            }
+        }
+    }
+    return refs;
+}
+function ensureServiceLayer(flattenedSchema, layerId) {
+    flattenedSchema.serviceLayers ||= {};
+    let serviceLayer = flattenedSchema.serviceLayers[layerId];
+    if (!serviceLayer) {
+        serviceLayer = {
+            layerId,
+            schemaVersion: '4.0.0',
+            shapes: {},
+            queries: {},
+            mutations: {}
+        };
+        flattenedSchema.serviceLayers[layerId] = serviceLayer;
+    }
+    return serviceLayer;
+}
+function rewriteLayerId(localShapes, layerId, query) {
+    const newQuery = deepClone(query);
+    const propertyVisitor = (propSchema, propSchemaPath) => {
+        const ref = (propSchema.items ?? propSchema)['@ref'];
+        if (ref) {
+            const [argsLayerId, shapeName] = splitAtRef(ref);
+            if (argsLayerId === 'local' && !localShapes[shapeName]) {
+                const path = propSchemaPath.concat(propSchema.items ? ['items', '@ref'] : ['@ref']);
+                set(newQuery, path, `${layerId}:${shapeName}`);
+            }
+        }
+    };
+    if (query.args) {
+        if (typeof query.args === 'string') {
+            const [argsLayerId, shapeName] = splitAtRef(parseTemplateShape(query.args).shapeName);
+            if (argsLayerId === 'local' && !localShapes[shapeName]) {
+                newQuery.args = `${layerId}:${shapeName}`;
+            }
+        }
+        else {
+            visitSchemaProperties(query.args, ['args'], propertyVisitor);
+        }
+    }
+    if (typeof query.shape === 'string') {
+        const [argsLayerId, shapeName] = splitAtRef(parseTemplateShape(query.shape).shapeName);
+        if (argsLayerId === 'local' && !localShapes[shapeName]) {
+            newQuery.shape = `${layerId}:${shapeName}`;
+        }
+    }
+    else {
+        const ref = query.shape.items['@ref'];
+        if (ref) {
+            const [argsLayerId, shapeName] = splitAtRef(ref);
+            if (argsLayerId === 'local' && !localShapes[shapeName]) {
+                set(newQuery, ['shape', 'items', '@ref'], `${layerId}:${shapeName}`);
+            }
+        }
+    }
+    return newQuery;
+}
+function assignQueries(localShapes, queries, layerId, layerQueries) {
+    for (const [queryName, query] of Object.entries(layerQueries)) {
+        queries[queryName] = rewriteLayerId(localShapes, layerId, query);
+    }
+}
+export function flattenSchema(projectSchema, getLayer) {
+    const { layers, ...rest } = projectSchema;
+    const flattenedSchema = {
+        ...rest,
+        shapes: {},
+        queries: {},
+        mutations: {},
+        workflows: {},
+        forms: {}
+    };
+    const filteredLayers = layers
+        .reverse()
+        .map((layer) => {
+        const config = typeof layer === 'string' ? { ...layerDefaults, id: layer } : layer;
+        const layerSchema = getLayer(config.id);
+        if (!layerSchema) {
+            throw new Error(`Unable to flatten schema for project ${projectSchema.projectId}. Cannot get layer ${config.id}`);
+        }
+        return config.visibility?.length ? filterLayer(layerSchema, config.visibility) : undefined;
+    })
+        .filter(isDefined);
+    for (const filteredLayer of filteredLayers) {
+        const { layerId } = filteredLayer;
+        // Preserve original queries
+        if (projectSchema.services?.[layerId]) {
+            const serviceLayer = ensureServiceLayer(flattenedSchema, layerId);
+            if (serviceLayer.queries && filteredLayer.queries) {
+                Object.assign(serviceLayer.queries, filteredLayer.queries);
+            }
+            if (serviceLayer.mutations && filteredLayer.mutations) {
+                Object.assign(serviceLayer.mutations, filteredLayer.mutations);
+            }
+        }
+        if (filteredLayer.workflows) {
+            Object.assign(flattenedSchema.workflows, filteredLayer.workflows);
+        }
+        if (flattenedSchema.forms && filteredLayer.forms) {
+            Object.assign(flattenedSchema.forms, filteredLayer.forms);
+        }
+        if (filteredLayer.shapes) {
+            assignShapes(flattenedSchema.shapes, filteredLayer.shapes);
+        }
+    }
+    for (const filteredLayer of filteredLayers) {
+        if (filteredLayer.queries) {
+            assignQueries(flattenedSchema.shapes, flattenedSchema.queries, filteredLayer.layerId, filteredLayer.queries);
+        }
+        if (filteredLayer.mutations) {
+            assignQueries(flattenedSchema.shapes, flattenedSchema.mutations, filteredLayer.layerId, filteredLayer.mutations);
+        }
+    }
+    // Preserve original service schema shapes
+    for (const refStr of collectServiceRefs(flattenedSchema, getLayer)) {
+        const [layerId, shapeName] = splitAtRef(refStr);
+        if (layerId !== 'local') {
+            const shape = getLayer(layerId)?.shapes?.[shapeName];
+            if (shape) {
+                const serviceLayer = ensureServiceLayer(flattenedSchema, layerId);
+                serviceLayer.shapes ||= {};
+                serviceLayer.shapes[shapeName] = shape;
+            }
+        }
+    }
+    return flattenedSchema;
+}

package/dist/layers/refs.d.ts

@@ -0,0 +1,102 @@
+import type { Maybe } from '@takeshape/util';
+import type { PropertySchemaV4_0_0, QueryJSONV4_0_0, ReturnShapeV4_0_0, ShapeJSONV4_0_0, ShapeMapV4_0_0 } from '../project-schema/index.ts';
+import type { SchemaPath } from '../types/index.ts';
+/**
+ * This interface describes a parsed `@ref` or `$ref`.
+ * The intended usage is to convert a schema with a ref to a RefItem which can then
+ * be passed to the various rich utilities in this file.
+ */
+export type RefItem = {
+    typeName: string;
+    layerId: string;
+    template?: string;
+};
+/**
+ * Adds a schema path, needed when visiting a whole schema to report errors.
+ */
+export type RefItemWithPath = {
+    path: SchemaPath;
+} & RefItem;
+/**
+ * Safely turn a "template" shape reference (`@args`, `args`, `shape`) into a `RefItem`
+ *
+ * @param context A partial project schema
+ * @param refExpression
+ * A ref expression might include "template" name and refer to a local or remote
+ * shape, `Foo` or `CreateArgs<Foo>` or `CreateArgs<remote:Foo>`.*
+ */
+export declare function refExpressionToRefItem(refExpression: string): RefItem;
+/**
+ * Sugar for converting a `refExpression` directly into a shape, without the
+ * intermediate `refItem`.
+ *
+ * @param context A partial project schema
+ * @param refExpression
+ * A ref expression might include "template" name and refer to a local or remote
+ * shape, `Foo` or `CreateArgs<Foo>` or `CreateArgs<remote:Foo>`.
+ */
+export declare function refExpressionToShape(shapes: ShapeMapV4_0_0, refExpression: string): Maybe<ShapeJSONV4_0_0>;
+/**
+ * Provided a service name and a referenced type. Supports 2 or 3 part
+ * references, e.g., `shopify:my-store:ProductInput` or `my-store:ProductInput`.
+ *
+ * @returns
+ * A 2 member array, where 0 is the service name, 1 is the referenced type.
+ */
+export declare function splitAtRef(atRef: string): [string, string];
+/**
+ * Parses and returns a typeName, serviceKey, and potentially a namespace for
+ * the type.
+ */
+export declare function atRefToRefItem(atRef: string, template?: string): RefItem;
+/**
+ * Given a content schema and project schema, finds a `@ref` or `$ref` and
+ * returns a `RefItem` suitable for loading a referenced schema...
+ */
+export declare function getRef(refSchema: PropertySchemaV4_0_0): Maybe<RefItem>;
+export declare function getRefWithPath(refSchema: PropertySchemaV4_0_0, schemaPath?: SchemaPath): Maybe<RefItemWithPath>;
+/**
+ * Tests for a `@ref` or `$ref` property directly on the passed schema.
+ *
+ * @param schema Any schema that might could have a ref property.
+ */
+export declare function hasRefProperty(schema: PropertySchemaV4_0_0): boolean;
+/**
+ * From a schema with a ref, will return the top-level ref, and potentially
+ * a ref item from a nested `items` property.
+ */
+export declare function getRefOrItemsRef(refSchema: PropertySchemaV4_0_0, schemaPath?: SchemaPath): Maybe<RefItemWithPath>;
+/**
+ * Turns a `RefItem` into an `@ref`.
+ */
+export declare function refItemToString(refItem: RefItem): string;
+/**
+ * Get a Shape referenced by a `RefItem`.
+ */
+export declare function refItemToShape(shapes: ShapeMapV4_0_0, refItem: RefItem): Maybe<ShapeJSONV4_0_0>;
+/**
+ * Helper fn to omit `ref` props from the target schema, and then extend it with the source schema.
+ */
+export declare const omitRefAndExtend: (targetSchema: PropertySchemaV4_0_0, sourceSchema: PropertySchemaV4_0_0) => import("lodash").Omit<PropertySchemaV4_0_0, "@ref" | "$ref"> & PropertySchemaV4_0_0;
+/**
+ * If there is a $ref, this will insert a content schema from the top level
+ * in place of the reference.
+ */
+export declare function followRef(shapes: ShapeMapV4_0_0, contentSchema: PropertySchemaV4_0_0): PropertySchemaV4_0_0;
+/**
+ * Returns whether a schema has refs.
+ */
+export declare function hasRef(contentSchema: PropertySchemaV4_0_0): boolean;
+/**
+ * Returns whether a schema has refs which can be followed.
+ */
+export declare function hasResolvableRef(shapes: ShapeMapV4_0_0, contentSchema: PropertySchemaV4_0_0): boolean;
+export declare function getArgsReferenceWithPath(argsSchema: PropertySchemaV4_0_0 | QueryJSONV4_0_0, schemaPath?: SchemaPath): Maybe<RefItemWithPath>;
+export declare function dereferenceSchema(shapes: ShapeMapV4_0_0, shapeOrFieldSchema: PropertySchemaV4_0_0, schemaPath?: SchemaPath): PropertySchemaV4_0_0;
+export type ParsedReturnShape = {
+    isArray: boolean;
+    template?: string;
+    shapeName: string;
+    ref?: RefItem;
+};
+export declare function parseReturnShape(shape: ReturnShapeV4_0_0): ParsedReturnShape;