api/party/model.proto (309 lines of code) (raw):
/**
* Copyright 2022 Google LLC
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
syntax = "proto3";
package google.retail.party.pb;
// Go Lang Options
option go_package = "github.com/GoogleCloudPlatform/retail-data-model/party/pb";
// Java Options
option java_package = "com.google.retail.party.pb";
option java_multiple_files = true;
import "google/protobuf/timestamp.proto";
import "api/common/model.proto";
import "api/enums/currency.proto";
import "api/enums/party.proto";
import "api/enums/lang.proto";
message PartyTemplate {
enum Type {
PERSON = 0;
ORGANIZATION = 1;
HOUSEHOLD = 2;
COMMUNITY = 3;
}
message Field {
bool required = 1;
bool repeatable = 2;
string validation_regex = 3;
string name = 4;
string description = 5;
}
string id = 1;
int32 version = 2;
Type party_type_id = 3;
string name = 4;
string description = 5;
repeated Field fields = 6;
}
message FieldValue {
}
/*
* A person or organization that exchanges information,
* tender and/or goods and *services with a retailer.
*/
message Party {
google.retail.common.pb.VersionID id = 1;
string party_template_id = 2;
int32 path_template_version = 3;
}
/*
* Represents the effective state of a party. It's a best practice to keep a
* history of party registration events hence the effective and expiration
* dates.
*/
message PartyRegistrationState {
enum Registration {
UNKNOWN_CONSUMER = 0;
REGISTERED_NOT_VALIDATED = 1;
REGISTERED_VALIDATED = 2;
UNREGISTERED = 3;
}
google.retail.common.pb.VersionID id = 1;
google.retail.common.pb.VersionID party_id = 2;
Registration registration = 3;
google.protobuf.Timestamp effective_date = 4;
google.protobuf.Timestamp expiration_date = 5;
bool do_not_call = 6;
bool do_not_email = 7;
bool do_not_share = 8;
bool do_not_track = 9;
}
/*
* PartyRole identifies, names and describes different parts a Party may play
* when interacting with a retailer. PartyRole is an important concept because
* is enables one person or organization to play multiple parts (e.g. a worker
* who is also a customer) without having to replicate name, address and other
* contract data.
*
* Example: Consumer, Veteran, Worker, Vendor, Supplier, Tax Authority
*
* For more explicitly modeled PartyRole type see Logical 06310 Party-Role VIew
* subject area).
*/
message PartyRole {
google.retail.common.pb.VersionID id = 1;
}
/*
* A description for a party identification type such as a drivers license
*/
message PartyIdentityDefinition {
google.retail.common.pb.VersionID id = 1;
/*
* A set of retailer specific keys such as 'state', 'country'
* used to narrow applicability.
*/
map<string, string> key_set = 2;
/*
* Field level definitions such as "Name":"The name on the ID".
*/
map<string, string> meta_definitions = 3;
/*
* The Field name plus a validation expression such as "Name","\w+ \w+"
*/
map<string, string> meta_validations = 4;
}
/*
* An official number that may be used to identify a Party. People have multiple
* forms of such identification: Drivers License number , Passport number,
* Insurance group and policy numbers, etc.
*
* Note that PartyIdentification could also apply to social security number,
* credit/debit accounts but these SHOULD never be retained by a retailer except
* where explicitly permitted for tax or regulatory purposes.
*
*/
message PartyIdentification {
string party_id = 1;
string party_identification_definition_name = 2;
int32 party_identification_definition_version = 3;
map<string, string> values = 4;
}
/*
* Temporal record of when the Party became (and ceased to be) related to the
* Retail Enterprise via the PartyRole.
*
* This entity represents the different varieties of relationships that may
* exist between the retailer and other organizations and individuals (parties)
* through time (hence the effective and expiration dates).
*/
message PartyRoleAssignment {
string party_id = 1;
string party_role_type_id = 2;
/*
* A retailer assigned code denoting the current status of the
* PartyRoleAssignment.
*/
string status_code = 3;
/*
* A code that identifies a group of PARTY ROLES. This is used for subtyping
* the PARTY ROLEs.
*/
google.protobuf.Timestamp effective_date = 4;
google.protobuf.Timestamp expiration_date = 5;
}
/*
* A separate legal entity which conducts retail operations on behalf of the
* retail enterprise in some geographical location.
*/
message OperationalParty {
string id = 1;
string party_role_assignment_id = 2;
}
/*
* A record for tracking legal entity operations through time and changes
*/
message EffectiveParty {
string party_id = 1;
google.protobuf.Timestamp effective_date = 2;
google.protobuf.Timestamp expiration_date = 3;
}
/*
* A Household is an identifiable, named, defined group of Person party subtypes
* that make retail related decisions together. Traditionally households are
* tied to residential addresses and represented nuclear families. Today these
* qualifiers of household don't always apply so it is a more generic way to
* gather individual parties into a economic decision making unit.
*
* Households share some characteristics with Organization and Community - but
* they are important to retailers because they represent groups of parties that
* purchase and consume products and services as an economic decision making
* unit. In ARTS we are distinguishing Households from Organizations (which are
* more typically representing commercial, public of charitable business
* establishments) and communities which may or may not have clearly delineated
* economic decision making capacity.
*/
message Household {
EffectiveParty id = 1;
string name = 2;
google.retail.enums.currency.Currency primary_currency = 3;
double household_income = 4;
reserved 5 to 99;
map<string, string> additional_dimensions = 100;
}
/*
* A sub-type of party that represents an individual of interest to the retail
* store or retail enterprise.
*/
message Person {
EffectiveParty id = 1;
string language_id = 2;
string title = 3;
string first_name = 4;
// A code denoting what kind of name the FirstName is, possible values
// include: GivenName, OtherGivenName, FamilyName, Patronymic
string first_name_type = 5;
string middle_name = 6;
string middle_name_type = 7;
string last_name = 8;
string last_name_type = 9;
string suffix = 10;
string sorting_name = 11;
string mailing_name = 12;
string official_name = 13;
reserved 14 to 29;
google.retail.enums.party.Gender gender = 30;
google.retail.enums.party.Pronoun pronoun = 31;
google.retail.enums.party.MaritalStatus marital_status = 32;
google.retail.enums.party.LifeStage life_stage = 33;
google.retail.enums.party.Race race = 34;
google.retail.enums.party.Ethnicity ethnicity = 35;
google.retail.enums.party.ReligionGroup religion_group = 36;
google.retail.enums.party.Religion religion = 37;
google.retail.enums.party.EmploymentStatus employment_status = 38;
google.retail.enums.party.Occupation occupation = 39;
google.retail.enums.currency.Currency primary_currency = 40;
reserved 41 to 99;
string annual_income_range = 100;
string disability_impairment_type = 101;
string personality_type = 102;
string lifestyle_type = 103;
string personal_value_type = 104;
string value_attitude_lifestyle_type = 105;
string dietary_habit_type = 106;
string consumer_credit_score = 107;
string consumer_credit_rating_service_name = 108;
reserved 109 to 199;
map<string, string> additional_dimensions = 200;
}
/*
* A company, association, institution, or other enterprise of interest to a
* retail store or retail enterprise.
*
* Note that because this is a RETAIL view of customer organizations is is more
* limited than a wholesale or manufacturing view of trading partner. This
* treatment of Organization is not and should not be used as a substitute for
* B2B trading partner information.
*/
message Organization {
EffectiveParty id = 1;
string legal_name = 2;
string trade_name = 3;
string business_activity = 4;
google.retail.enums.party.BusinessClassification
business_classification = 5;
string jurisdiction = 6;
google.protobuf.Timestamp open_for_business = 7;
google.protobuf.Timestamp closed_for_business = 8;
google.protobuf.Timestamp incorporation_date = 9;
google.protobuf.Timestamp fiscal_year_end_date = 10;
google.retail.enums.lang.Language primary_language = 11;
repeated google.retail.enums.lang.Language supported_languages =
12;
google.retail.enums.currency.Currency primary_currency = 13;
double local_annual_revenue_amount = 14;
double global_annual_revenue_amount = 15;
int32 local_employee_count = 16;
int32 global_employee_count = 17;
reserved 18 to 49;
google.retail.enums.party.ReligionGroup religion_group = 50;
google.retail.enums.party.Religion religion = 51;
reserved 52 to 99;
bool bankruptcy = 100;
bool duns_information = 101;
reserved 102 to 199;
map<string, string> additional_dimensions = 200;
}
/*
* The D&B DUNS Number is a non-indicative, nine-digit number assigned to each
* business location in the D&B database having a unique, separate, and distinct
* operation, and is maintained solely by D&B. The D&B DUNS Number is used by
* industries and organizations around the world as a global standard for
* business identification and tracking. If you don`t have a D-U-N-S Number,
* you can get one for free through the SBS site.
*/
message OrganizationDUNSInformation {
EffectiveParty id = 1;
string duns_number = 2;
string duns_rating = 3;
}
/*
* Historic perspective of an organizations statuses of bankruptcy reputation.
*/
message OrganizationBankruptcy {
EffectiveParty id = 1;
google.protobuf.Timestamp date = 2;
google.protobuf.Timestamp emergence_date = 3;
google.retail.enums.party.Bankruptcy bankruptcy = 4;
string additional_information = 5;
}
/*
* Community represents a group of parties associated to a formal community
*/
message Community {
EffectiveParty id = 1;
string Name = 2;
google.retail.enums.currency.Currency primary_currency = 3;
reserved 4 to 99;
map<string, string> additional_dimensions = 100;
}