schema/common/validation.proto

// Copyright 2017 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

syntax = "proto3";
package common;
option go_package = "chromium.googlesource.com/enterprise/cel/go/common";

import "google/protobuf/descriptor.proto";

message Validation {
  enum FieldType {
    // No validation is to be performed.
    UNKNOWN = 0;

    // When applied to a `string` field, implies that the field value cannot be
    // empty. This is implied for any field that has a non-empty external
    // reference (i.e. `ref != ""`), or the validation type is
    // [LABEL](#Validation.FieldType.LABEL), [FQDN](#Validation.FieldType.FQDN)
    // or [ORGLABEL](#Validation.FieldType.ORGLABEL).
    //
    // When applied to a `repeated` field, implies that there must be at least
    // one instance of the field.
    //
    // When applied to `oneof` implies that at least one of the alternatives
    // must be specified.
    //
    // When applied to a `map` implies that there should be at least one
    // mapping.
    //
    // E.g.: Declare the `h` field of Foo message to be required:
    //
    // ``` proto
    //   message Foo {
    //     string h = 1 [(v).type=REQUIRED]
    //   }
    // ```
    REQUIRED = 1;

    // The field value cannot be empty and must match the `<label>` production
    // in [RFC 1035][]. This validation type is applied by default for for any
    // field named 'name'.
    //
    // [RFC 1035]: https://www.ietf.org/rfc/rfc1035.txt
    LABEL = 2;

    // The field value cannot be empty, and must match the `<subdomains>`
    // production in [RFC 1035][]. Can only be applied to `string` fields.
    FQDN = 3;

    // A label with an optional org component. These look like:
    // `example.com:foo`. Cannot be empty.
    ORGLABEL = 4;

    // This is an output field and is not expected to be populated in a asset
    // manifest input. The field will be populated during the deployment
    // process and made available to downstream consumers of the manifest.
    OUTPUT = 5;

    // This is a runtime field. It's value is only available *after* the
    // corresponding asset has been deployed and running. Runtime values can be
    // looked up via RuntimeConfiguration service from within the lab.
    //
    // Unlike [OUTPUT](#Validation.FieldType.OUTPUT) fields,
    // [RUNTIME](#Validation.FieldType.RUNTIME) fields can only be defined on
    // top-level assets. In other words, they can only appear if the asset in
    // question is a direct child of the HostEnvironment or AssetManifest
    // messages.
    RUNTIME = 6;

    // This is a top-level field. This type is applicable only to fields that
    // constititue top level collections. Any element in a top level collection
    // that doesn't have a rooted reference will be removed during the pruning
    // phase.
    //
    // See description of pruning in
    // https://chromium.googlesource.com/enterprise/cel/+/HEAD/docs/deployment.md#Pruning.
    TOPLEVEL = 7;
  }
  FieldType type = 1;

  // The foreign key. If non-empty, designates that this string field is a
  // reference to a collection designated by `ref`.
  //
  // E.g.: Declare `network` to be a field that refers to an `asset.network` by
  // name.
  //
  // ``` proto
  //   message Foo {
  //     string network = 1 [(v).ref="asset.network"]
  //   }
  // ```
  //
  // The annotated field must be a string.
  string ref = 2;

  // Indicates that the value is optional. By default adding an annotation to a
  // field marks it as a required field. Setting `optional` to true negates
  // that.
  oneof optional_flag { bool optional = 3; }
}

// Field options. These are used to annotate fields in asset and host messages
// to indicate foreign keys, and additional validation requirements.
extend google.protobuf.FieldOptions {
  // See Validation above.
  //
  // Use as:
  //
  // ``` proto
  //   message Foo {
  //     string my_field = 1 [(v).type=<type>];
  //   }
  // ```
  //
  // Or more commonly:
  //
  // ``` proto
  //   message Foo {
  //     string my_field = 1 [(common.v).type=<type>];
  //   }
  // ```
  //
  // Or:
  //
  // ``` proto
  //   message Foo {
  //     string my_field = 1 [(common.v)={type:<type>, ref:"<key>"}];
  //   }
  // ```
  Validation v = 50000;
}