001/*
002 * Copyright 2026 Revetware LLC.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package com.revetsec.scim;
018
019import com.google.errorprone.annotations.CheckReturnValue;
020import com.revetsec.internal.json.AsciiCase;
021import org.jspecify.annotations.NonNull;
022import org.jspecify.annotations.Nullable;
023import javax.annotation.concurrent.Immutable;
024import javax.annotation.concurrent.NotThreadSafe;
025import java.util.List;
026import java.util.Objects;
027import java.util.Optional;
028
029/**
030 * Immutable SCIM schema registration. Schema identifiers are bounded absolute URI strings;
031 * they are never fetched. Application schemas cannot override common resource attributes.
032 *
033 * @since 1.0.0
034 */
035@Immutable
036@CheckReturnValue
037public final class ScimSchema {
038    private final @NonNull String id;
039    private final @NonNull String name;
040    private final @Nullable String description;
041    private final @NonNull List<@NonNull ScimAttributeDefinition> attributes;
042    private final boolean discovery;
043
044    private ScimSchema(@NonNull Builder builder, boolean discovery) {
045        if (builder.name == null)
046            throw new IllegalStateException("A SCIM schema requires a name.");
047        id = builder.id;
048        name = builder.name;
049        description = builder.description;
050        attributes = builder.attributes;
051        this.discovery = discovery;
052        ScimSchemas.requireDistinctAttributes(attributes);
053        int count = 0;
054        for (ScimAttributeDefinition definition : attributes) {
055            count += definition.definitionCount();
056            if (!discovery) {
057                if (ScimSchemas.isCommonName(definition.getName()) || AsciiCase.fold(definition.getName()).equals("$ref"))
058                    throw new IllegalArgumentException("Application schemas cannot override common SCIM attributes.");
059                for (ScimAttributeDefinition child : definition.getSubAttributes())
060                    if (child.getType() == ScimAttributeType.COMPLEX)
061                        throw new IllegalArgumentException("Nested complex application SCIM attributes are unsupported.");
062            }
063        }
064        ScimSchemas.requireDefinitionCount(count);
065    }
066
067    /**
068     * Starts an application schema with its required absolute URI identifier.
069     * @param id the required schema identifier
070     * @return a new builder
071     * @since 1.0.0
072     */
073    public static @NonNull Builder withId(@NonNull String id) { return new Builder(ScimSchemas.requireSchemaId(id)); }
074
075    /**
076     * Returns the schema URI identifier.
077     * @return the schema URI identifier
078     * @since 1.0.0
079     */
080    public @NonNull String getId() { return id; }
081
082    /**
083     * Returns the human-readable schema name.
084     * @return the human-readable schema name
085     * @since 1.0.0
086     */
087    public @NonNull String getName() { return name; }
088
089    /**
090     * Returns the optional schema description.
091     * @return the optional schema description
092     * @since 1.0.0
093     */
094    public @NonNull Optional<@NonNull String> getDescription() { return Optional.ofNullable(description); }
095
096    /**
097     * Returns the immutable schema-specific definitions. Common resource definitions are inherited.
098     * @return the immutable schema-specific definitions
099     * @since 1.0.0
100     */
101    public @NonNull List<@NonNull ScimAttributeDefinition> getAttributes() { return attributes; }
102
103    /**
104     * Returns the shared standard User schema, with reviewed RFC corrections.
105     * @return the standard schema
106     * @since 1.0.0
107     */
108    public static @NonNull ScimSchema userInstance() { return ScimSchemas.user(); }
109
110    /**
111     * Returns the shared standard Group schema, with reviewed RFC corrections.
112     * @return the standard schema
113     * @since 1.0.0
114     */
115    public static @NonNull ScimSchema groupInstance() { return ScimSchemas.group(); }
116
117    /**
118     * Returns the shared standard Enterprise User extension schema, with reviewed RFC corrections.
119     * @return the standard schema
120     * @since 1.0.0
121     */
122    public static @NonNull ScimSchema enterpriseUserInstance() { return ScimSchemas.enterpriseUser(); }
123
124    /**
125     * Returns the shared standard ServiceProviderConfig discovery schema, with reviewed RFC corrections.
126     * @return the standard schema
127     * @since 1.0.0
128     */
129    public static @NonNull ScimSchema serviceProviderConfigInstance() { return ScimSchemas.serviceProviderConfig(); }
130
131    /**
132     * Returns the shared standard ResourceType discovery schema, with reviewed RFC corrections.
133     * @return the standard schema
134     * @since 1.0.0
135     */
136    public static @NonNull ScimSchema resourceTypeInstance() { return ScimSchemas.resourceType(); }
137
138    /**
139     * Returns the shared standard Schema discovery schema, with reviewed RFC corrections.
140     * @return the standard schema
141     * @since 1.0.0
142     */
143    public static @NonNull ScimSchema schemaInstance() { return ScimSchemas.schema(); }
144
145    /**
146     * Compares semantic schema registrations, folding the schema identifier.
147     * @param other the comparison value
148     * @return whether registrations have equal characteristics
149     * @since 1.0.0
150     */
151    @Override public boolean equals(@Nullable Object other) {
152        return this == other || (other instanceof ScimSchema schema && discovery == schema.discovery
153                && AsciiCase.fold(id).equals(AsciiCase.fold(schema.id)) && name.equals(schema.name)
154                && Objects.equals(description, schema.description) && attributes.equals(schema.attributes));
155    }
156
157    /**
158     * Returns the semantic registration hash.
159     * @return the semantic hash
160     * @since 1.0.0
161     */
162    @Override public int hashCode() { return Objects.hash(AsciiCase.fold(id), name, description, attributes, discovery); }
163
164    /**
165     * Returns a fixed redacted description.
166     * @return a fixed redacted description
167     * @since 1.0.0
168     */
169    @Override public @NonNull String toString() { return "ScimSchema{<redacted>}"; }
170
171    boolean isDiscovery() { return discovery; }
172    static @NonNull ScimSchema fromDiscovery(@NonNull Builder builder) { return new ScimSchema(builder, true); }
173
174    /**
175     * Mutable, non-thread-safe schema configuration. Null restores the stated default.
176     * @since 1.0.0
177     */
178    @NotThreadSafe
179    @CheckReturnValue
180    public static final class Builder {
181        private final @NonNull String id;
182        private @Nullable String name;
183        private @Nullable String description;
184        private @NonNull List<@NonNull ScimAttributeDefinition> attributes = List.of();
185        private Builder(@NonNull String id) { this.id = id; }
186
187        /**
188         * Sets the required schema name; null restores unset.
189         * @param value the name, or null to restore unset
190         * @return this builder
191         * @since 1.0.0
192         */
193        public @NonNull Builder name(@Nullable String value) {
194            name = value == null ? null : ScimSchemas.requireName(value); return this;
195        }
196
197        /**
198         * Sets the optional description; null restores absent.
199         * @param value the description, or null to restore absent
200         * @return this builder
201         * @since 1.0.0
202         */
203        public @NonNull Builder description(@Nullable String value) {
204            description = value == null ? null : ScimSchemas.requireText(value, false); return this;
205        }
206
207        /**
208         * Replaces and snapshots the complete bounded definition list; null restores empty.
209         * @param value definitions, or null to restore empty
210         * @return this builder
211         * @since 1.0.0
212         */
213        public @NonNull Builder attributes(@Nullable List<@NonNull ScimAttributeDefinition> value) {
214            attributes = value == null ? List.of() : ScimSchemas.attributes(value); return this;
215        }
216
217        /**
218         * Checks application-resource characteristics and creates an immutable schema.
219         * @return the schema
220         * @since 1.0.0
221         */
222        public @NonNull ScimSchema build() { return new ScimSchema(this, false); }
223    }
224}