Guide To Installing View Schema

Updated at 1785250296000

View schema is a mechanism for describing the structure of a view in EzyPlatform. Instead of requiring AI or MCP to guess which template a page uses, which variables are available, or which fragments are involved, the system allows each module to register a clear schema for each viewUri.

When MCP needs to understand a view, it can look up the schema by URI to know:

Which template the view uses.
What business purpose the view has.
Which variables are passed to the view.
The data type, nested fields, example, and required status of each variable.
Whether the view uses page fragments.
Any additional metadata when needed.

Main Components

The View schema mechanism has three main components:

ViewSchema: describes a view.
ViewSchemaFetcher: provides the schema for a specific URI.
ViewMultipleSchemaFetcher: groups multiple ViewSchemaFetcher instances.
ViewSchemaFetcherManager: collects fetchers and allows schema lookup by viewUri.

A ViewSchema contains the following main information:

ViewSchema.builder()
    .template("users")
    .description("User list page")
    .variables(...)
    .pageFragmentPageName(...)
    .pageFragmentNames(...)
    .properties(...)
    .build();

Where:

template: the template name of the view.
description: a short explanation that helps AI understand the view.
variables: the list of variables passed to the template.
pageFragmentPageName: the page name used for fragments, if any.
pageFragmentNames: the list of fragments used by the view.
properties: additional metadata.

How It Works

flowchart TD
    A[Module defines ViewSchemaFetcher] --> B[Register in bean container]
    C[Module with multiple views defines ViewMultipleSchemaFetcher] --> B
    B --> D[ViewSchemaFetcherManager initializes lazily]
    D --> E[Collect direct ViewSchemaFetcher instances]
    D --> F[Collect fetchers from ViewMultipleSchemaFetcher]
    E --> G[Build map by viewUri]
    F --> G
    H[MCP or integration layer needs to understand a view] --> I[Look up schema by viewUri]
    I --> G
    G --> J[Return ViewSchema]

The manager does not scan template files directly. It only collects beans that have already been registered in the container. Therefore, if you want MCP to understand a view, the module must explicitly declare a fetcher for that view.

Installing A View Schema

For a single view, create a class that implements ViewSchemaFetcher and register it as a singleton.

import com.tvd12.ezyfox.bean.annotation.EzySingleton;
import org.youngmonkeys.ezyplatform.data.ViewSchema;
import org.youngmonkeys.ezyplatform.fetcher.ViewSchemaFetcher;

import java.util.Arrays;

@EzySingleton
public class UserListViewSchemaFetcher implements ViewSchemaFetcher {

    @Override
    public String getViewUri() {
        return "/users";
    }

    @Override
    public ViewSchema getSchema() {
        return ViewSchema.builder()
            .template("users")
            .description("Page that displays the user list")
            .variables(Arrays.asList(
                ViewSchema.DataSchema.builder()
                    .name("users")
                    .dataType(java.util.List.class)
                    .itemType(UserModel.class)
                    .description("List of users displayed on the page")
                    .build(),
                ViewSchema.DataSchema.builder()
                    .name("keyword")
                    .dataType(String.class)
                    .required(false)
                    .description("Current search keyword")
                    .example("john")
                    .build()
            ))
            .build();
    }
}

After this bean is recognized by the container, the manager will collect it automatically, and MCP can look up the schema by the /users URI.

Installing Multiple View Schemas

If a module has multiple views, you can group them with ViewMultipleSchemaFetcher.

import com.tvd12.ezyfox.bean.annotation.EzySingleton;
import org.youngmonkeys.ezyplatform.fetcher.ViewMultipleSchemaFetcher;
import org.youngmonkeys.ezyplatform.fetcher.ViewSchemaFetcher;

import java.util.Arrays;
import java.util.List;

@EzySingleton
public class UserViewSchemasFetcher implements ViewMultipleSchemaFetcher {

    @Override
    public List<ViewSchemaFetcher> getViewSchemaFetchers() {
        return Arrays.asList(
            new UserListViewSchemaFetcher(),
            new UserDetailViewSchemaFetcher(),
            new UserEditViewSchemaFetcher()
        );
    }
}

This approach is useful when you want to keep all schemas for a group of views in one place.

Declaring Template Variables

Each variable in variables uses ViewSchema.DataSchema. A variable can describe:

name: the variable name in the template.
dataType: the main data type.
itemType: the item type if the variable is a list.
arrayItemType: the item type if the variable is an array.
keyType, valueType: key/value types if the variable is a map.
required: whether the variable is required. The default is true.
description: the meaning of the variable.
example: an example value.
fields: nested fields if the variable is a complex object.
properties: additional metadata.

Example of describing an object with nested fields:

ViewSchema.DataSchema.builder()
    .name("user")
    .dataType(UserModel.class)
    .description("User information")
    .field(
        ViewSchema.DataSchema.builder()
            .name("displayName")
            .dataType(String.class)
            .description("Display name")
            .build()
    )
    .field(
        ViewSchema.DataSchema.builder()
            .name("email")
            .dataType(String.class)
            .required(false)
            .description("Contact email")
            .build()
    )
    .build();

URI Rules

getViewUri() is the schema identifier. This URI should match the URI used to render the view in the system.

Example:

@Override
public String getViewUri() {
    return "/admin/users";
}

Notes:

If the URI is not found, the manager returns null.
Direct ViewSchemaFetcher instances should not share the same URI.
If a schema from ViewMultipleSchemaFetcher has the same URI as a direct schema, the schema from ViewMultipleSchemaFetcher overwrites the existing one.
Do not rely on the order of the full schema list returned by the manager.

How MCP Uses It

MCP can use View schema as a metadata layer to understand EzyPlatform UI and templates.

sequenceDiagram
    participant MCP
    participant Manager as ViewSchemaFetcherManager
    participant Fetcher as ViewSchemaFetcher
    participant Schema as ViewSchema

    MCP->>Manager: getViewSchemaByUri("/users")
    Manager->>Fetcher: Find fetcher by URI
    Fetcher-->>Manager: View schema
    Manager-->>MCP: ViewSchema
    MCP->>MCP: Understand template, variables, fragments, metadata

With this mechanism, AI does not need to read or infer the whole template to understand a view. The schema acts as a structured, stable, and easier-to-consume description.

Suggestions When Writing Schemas

Write a short but useful description that provides enough business context. Variable names should match the actual variable names used in the template. For complex objects, declare important fields so AI can understand the data structure instead of only seeing a general class.

Do not include sensitive data in example or properties. View schema should describe structure, not contain real runtime user data.

Verification After Installation

After adding a fetcher, make sure that:

The class is registered in the bean container.
getViewUri() matches the view URI.
template matches the rendered template name.
Variables in variables match the data passed from the controller to the template.
There are no unintended duplicate URIs.
MCP or the integration layer can call the manager to retrieve schema by URI.

Conclusion

View schema is the official description layer between the view runtime and MCP. Each module only needs to register the corresponding ViewSchemaFetcher instances for its views, and the system will automatically collect schemas by URI. This helps AI understand EzyPlatform more accurately, reduces incorrect inference from templates, and creates a foundation for documentation generation, UI analysis, and better developer assistance.

Previous Page How to Install the Random Record Query Function