Transport Error Codes And Their Descriptive Essay

Examine the community and record your findings in a community description or overview for credibility and awareness.

 

  • What is a community?

  • What do we mean by understanding and describing the community?

  • Why make the effort to understand and describe your community?

  • Whom should you contact to gather information?

  • How do you go about understanding and describing the community?

For those of us who work in community health and development, it's important to understand community -- what a community is, and the specific nature of the communities we work in. Anything we do in a community requires us to be familiar with its people, its issues, and its history. Carrying out an intervention or building a coalition are far more likely to be successful if they are informed by the culture of the community and an understanding of the relationships among individuals and groups within it.

Taking the time and effort to understand your community well before embarking on a community effort will pay off in the long term. A good way to accomplish that is to create a community description -- a record of your exploration and findings. It's a good way to gain a comprehensive overview of the community -- what it is now, what it's been in the past, and what it could be in the future. In this section, we'll discuss how you might approach examining the community in some detail and setting down your findings in a community description.

What is a community?

While we traditionally think of a community as the people in a given geographical location, the word can really refer to any group sharing something in common. This may refer to smaller geographic areas -- a neighborhood, a housing project or development, a rural area -- or to a number of other possible communities within a larger, geographically-defined community.

These are often defined by race or ethnicity, professional or economic ties, religion, culture, or shared background or interest:

  • The Catholic community (or faith community, a term used to refer to one or more congregations of a specific faith).
  • The arts community
  • The African American community
  • The education community
  • The business community
  • The homeless community
  • The gay, lesbian, bisexual, and transgender community
  • The medical community
  • The Haitian community
  • The elderly community

These various communities often overlap. An African American art teacher, for example, might see herself (or be seen by others) as a member of the African American, arts, and/or education communities, as well as of a particular faith community. An Italian woman may become an intensely involved member of the ethnic and cultural community of her Nigerian husband. Whichever community defines your work, you will want to get to know it well.

What do we mean by understanding and describing the community?

Understanding the community entails understanding it in a number of ways. Whether or not the community is defined geographically, it still has a geographic context -- a setting that it exists in. Getting a clear sense of this setting may be key to a full understanding of it. At the same time, it's important to understand the specific community you're concerned with. You have to get to know its people -- their culture, their concerns, and relationships -- and to develop your own relationships with them as well.

  • Physical aspects. Every community has a physical presence of some sort, even if only one building. Most have a geographic area or areas they are either defined by or attached to. It's important to know the community's size and the look and feel of its buildings, its topography (the lay of the land -- the hills, valleys, rivers, roads, and other features you'd find on a map), and each of its neighborhoods. Also important are how various areas of the community differ from one another, and whether your impression is one of clean, well-maintained houses and streets, or one of shabbiness, dirt, and neglect.

    If the community is one defined by its population, then its physical properties are also defined by the population: where they live, where they gather, the places that are important to them. The characteristics of those places can tell you a great deal about the people who make up the community. Their self-image, many of their attitudes, and their aspirations are often reflected in the places where they choose -- or are forced by circumstance or discrimination -- to live, work, gather, and play.

  • Infrastructure. Roads, bridges, transportation (local public transportation, airports, train lines), electricity, land line and mobile telephone service, broadband service, and similar "basics" make up the infrastructure of the community, without which it couldn't function.
  • Patterns of settlement, commerce, and industry. Where are those physical spaces we've been discussing? Communities reveal their character by where and how they create living and working spaces. Where there are true slums --  substandard housing in areas with few or no services that are the only options for low-income people -- the value the larger community places on those residents seems clear. Are heavy industries located next to residential neighborhoods? If so, who lives in those neighborhoods? Are some parts of the community dangerous, either because of high crime and violence or because of unsafe conditions in the built or natural environment?
  • Demographics.  It's vital to understand who makes up the community.  Age, gender, race and ethnicity, marital status, education, number of people in household, first language -- these and other statistics make up the demographic profile of the population. When you put them together (e.g.,  the education level of black women ages 18-24), it gives you a clear picture of who community residents are.
  • History. The long-term history of the community can tell you about community traditions, what the community is, or has been, proud of, and what residents would prefer not to talk about. Recent history can afford valuable information about conflicts and factions within the community, important issues, past and current relationships among key people and groups -- many of the factors that can trip up any effort before it starts if you don't know about and address them.
  • Community leaders, formal and informal. Some community leaders are elected or appointed -- mayors, city councilors, directors of public works. Others are considered leaders because of their activities or their positions in the community -- community activists, corporate CEO's, college presidents, doctors, clergy.  Still others are recognized as leaders because, they are trusted for their proven integrity, courage, and/or care for others and the good of the community.
  • Community culture, formal and informal. This covers the spoken and unspoken rules and traditions by which the community lives. It can include everything from community events and slogans -- the blessing of the fishing fleet, the "Artichoke Capital of the World" -- to norms of behavior -- turning a blind eye to alcohol abuse or domestic violence -- to patterns of discrimination and exercise of power. Understanding the culture and how it developed can be crucial, especially if that's what you're attempting to change.
  • Existing groups.  Most communities have an array of groups and organizations of different kinds -- service clubs (Lions, Rotary, etc.), faith groups, youth organizations, sports teams and clubs, groups formed around shared interests, the boards of community-wide organizations (the YMCA, the symphony, United Way), as well as groups devoted to self-help, advocacy, and activism.  Knowing of the existence and importance of each of these groups can pave the way for alliances or for understanding opposition.
  • Existing institutions. Every community has institutions that are important to it, and that have more or less credibility with residents. Colleges and universities, libraries, religious institutions, hospitals -- all of these and many others can occupy important places in the community. It's important to know what they are, who represents them, and what influence they wield.
  • Economics.  Who are the major employers in the community?  What, if any, business or industry is the community's base? Who, if anyone, exercises economic power? How is wealth distributed? Would you characterize the community as poor, working, class, middle class, or affluent?  What are the economic prospects of the population in general and/or the population you're concerned with?
  • Government/Politics. Understanding the structure of community government is obviously important. Some communities may have strong mayors and weak city councils, others the opposite. Still other communities may have no mayor at all, but only a town manager, or may have a different form of government entirely.  Whatever the government structure, where does political power lie? Understanding where the real power is can be the difference between a successful effort and a vain one.
  • Social structure. Many aspects of social structure are integrated into other areas -- relationships, politics, economics -- but there are also the questions of how people in the community relate to one another on a daily basis, how problems are (or aren't) resolved, who socializes or does business with whom, etc. This area also includes perceptions and symbols of status and respect, and whether status carries entitlement or responsibility (or both).
  • Attitudes and values. Again, much of this area may be covered by investigation into others, particularly culture. What does the community care about, and what does it ignore? What are residents' assumptions about the proper way to behave, to dress, to do business, to treat others? Is there widely accepted discrimination against one or more groups by the majority or by those in power? What are the norms for interaction among those who with different opinions or different backgrounds?

We'll discuss all of these aspects of community in greater detail later in the section.

There are obviously many more aspects of community that can be explored, such as health or education.  The assumption here is that as part of an assessment, you'll aim for a general understanding of the community, as described in this section, and also assess, with a narrower focus, the specific aspects you're interested in.

Once you've explored the relevant areas of the community, you'll have the information to create a community description. Depending on your needs and information, this description might be anything from a two-or three-page outline to an in-depth portrait of the community that extends to tens of pages and includes charts, graphs, photographs, and other elements. The point of doing it is to have a picture of the community at a particular point in time that you can use to provide a context for your community assessment and to see the results of whatever actions you take to bring about change.

A community description can be as creative as you're capable of making it.  It can be written as a story, can incorporate photos and commentary from community residents (see Photovoice), can be done online and include audio and video, etc. The more interesting the description is, the more people are likely to actually read it.

Why make the effort to understand and describe your community?

You may at this point be thinking, "Can't I work effectively within this community without gathering all this information?" Perhaps, if it's a community you're already familiar with, and really know it well. If you're new to the community, or an outsider, however, it's a different story. Not having the proper background information on your community may not seem like a big deal until you unintentionally find yourself on one side of a bitter divide, or get involved in an issue without knowing about its long and tangled history.

Some advantages to taking the time to understand the community and create a community description include:

  • Gaining a general idea, even before an assessment, of the community's strengths and the challenges it faces.
  • Capturing unspoken, influential rules and norms. For example, if people are divided and angry about a particular issue, your information might show you an event in the community's history that explains their strong emotions on that subject.
  • Getting a feel for the attitudes and opinions of the community when you're starting work on an initiative.
  • Ensuring the security of your organization's staff and participants.  There may be neighborhoods where staff members or participants should be accompanied by others in order to be safe, at least at night. Knowing the character of various areas and the invisible borders that exist among various groups and neighborhoods can be extremely important for the physical safety of those working and living in the community.
  • Having enough familiarity with the community to allow you to converse intelligently with residents about community issues, personalities and geography. Knowing that you've taken the time and effort to get to know them and their environment can help you to establish trust with community members.  That can make both a community assessment and any actions and activities that result from it easier to conduct.
  • Being able to talk convincingly with the media about the community.
  • Being able to share information with other organizations or coalitions that work in the community so that you can collaborate or so that everyone's work can benefit.
  • Providing background and justification for grant proposals.
  • Knowing the context of the community so that you can tailor interventions and programs to its norms and culture, and increase your chances of success.

When should you make an effort to understand and describe the community?

  • When you're about to launch a community assessment.  The first step is to get a clear sense of the community, before more specifically assessing the area(s) you're interested in.
  • When you're new to a community and want to be well informed before beginning your work. If you've just started working in a community -- even if it's work you've been doing for years -- you will probably find that taking the time to write a community description enriches your work.
  • When you've been working in a community for any length of time and want to take stock. Communities are complex, constantly-changing entities. By periodically stopping to write a detailed description of your community, you can assess what approaches have worked and what haven't; new needs that have developed over time and old concerns that no longer require your effort and energy; and other information to help you better do your work.
  • When you're feeling like you're stuck in a rut and need a fresh perspective. Organizations have to remain dynamic in order to keep moving forward. Reexamining the community -- or perhaps examining it carefully for the first time -- can infuse an organization with new ideas and new purpose.
  • When you're considering introducing a new initiative or program and want to assess its possible success.Aside from when you first come to a community, this is probably the most vital time to do a community description.
  • When a funder asks you to, often as part of a funding proposal.

While researching and writing a community description can take time, your work can almost always benefit from the information you gather.

Whom should you contact to gather information?

Much of your best and most interesting information may come from community members with no particular credentials except that they're part of the community. It's especially important to get the perspective of those who often don't have a voice in community decisions and politics -- low-income people, immigrants, and others who are often kept out of the community discussion. In addition, however, there are some specific people that it might be important to talk to. They're the individuals in key positions, or those who are trusted by a large part of the community or by a particular population. In a typical community, they might include:

  • Elected officials
  • Community planners and development officers
  • Chiefs of police
  • School superintendents, principals, and teachers
  • Directors or staff of health and human service organizations
  • Health professionals
  • Clergy
  • Community activists
  • Housing advocates
  • Presidents or chairs of civic or service clubs -- Chamber of Commerce, veterans' organizations, Lions, Rotary, etc.
  • People without titles, but identified by others as "community leaders"
  • Owners or CEO's of large businesses (these may be local or may be large corporations with local branches)

How do you go about understanding and describing the community?

General Guidelines

To begin, let's look at some basic principles to keep in mind.

  • Be prepared to learn from the community. Assume that you have a lot to learn, and approach the process with an open mind. Listen to what people have to say. Observe carefully. Take notes -- you can use them later to generate new questions or to help answer old ones.
  • Be aware that people's speech, thoughts, and actions are not always rational. Their attitudes and behavior  are often best understood in the context of their history, social relations, and culture. Race relations in the U.S., for example, can't be understood without knowing some of the historical context -- the history of slavery, Jim Crow laws, and the work of Martin Luther King and the Civil Rights Movement.
  • Don't assume that the information people give you is necessarily accurate. There are a number of reasons why informants may tell you things that are inaccurate. People's perceptions don't always reflect reality, but are colored instead by what they think or what they think they know.  In addition, some may intentionally exaggerate or downplay particular conditions or issues for their own purposes or for what they see as the greater good. (The Chamber of Commerce or local government officials might try to make economic conditions look better than they are in the hopes of attracting new business to the community, for instance.)  Others may simply be mistaken about what they tell you  -- the geographical boundaries of a particular neighborhood, for example, or the year of an important event. Get information, particularly on issues, conditions, and relationships from many sources if you can. As time goes on, you'll learn who the always-reliable sources are.
  • Beware of activities that may change people's behavior. It's well known that people (and animals as well) can change their normal behavior as a result of knowing they're being studied.  Neighborhood residents may clean up their yards if they're aware that someone is taking the measure of the neighborhood. Community members may try to appear as they wish to be seen, rather than as they really are, if they know you're watching. To the extent that you can, try not to do anything that will change the way people go about their daily business or express themselves. That usually means being as unobtrusive as possible -- not being obvious about taking pictures or making notes, for instance. In some circumstances, it could mean trying to gain trust and insight through participant observation.

Participant observation is a technique that anthropologists use.  It entails becoming part of another culture, both to keep people in it from being influenced by your presence and to understand it from the inside.  Some researchers believe it addresses the problem of changing the culture by studying it, and others believe that it makes the problem worse.

  • Take advantage of the information and facilities that help shape the world of those who have lived in the community for a long time. Read the local newspaper (and the alternative paper, too, if there is one), listen to local radio, watch local TV, listen to conversation in cafes and bars, in barbershops and beauty shops.  You can learn a great deal about a community by immersing yourself in its internal communication. The Chamber of Commerce will usually have a list of area businesses and organizations, along with their contact people, which should give you both points of contact and a sense of who the people are that you might want to get in touch with. Go to the library -- local librarians are often treasure troves of information, and their professional goal is to spread it around. Check out bulletin boards at supermarkets and laundromats.  Even graffiti can be a valuable source of information about community issues.
  • Network, network, network.  Every contact you make in the community has the potential to lead you to more contacts. Whether you're talking to official or unofficial community leaders or to people you just met on the street, always ask who else they would recommend that you talk to and whether you can use their names when you contact those people. Establishing relationships with a variety of community members is probably the most important thing you can do to ensure that you'll be able to get the information you need, and that you'll have support for working in the community when you finish your assessment and begin your effort.

Gathering information

To find out about various aspects of the community, you'll need a number of different methods of gathering information. We've already discussed some of them, and many of the remaining sections of this chapter deal with them, because they're the same methods you'll use in doing a full community assessment. Here, we'll simply list them, with short explanations and links to sections where you can get more information about each.

  • Public records and archives. These include local, state, and federal government statistics and records, newspaper archives, and the records of other organizations that they're willing to share. Many of the public documents are available at public and/or university libraries and on line at government websites. Most communities have their own websites, which often contain valuable information as well.
  • Individual and group interviews. Interviews can range from casual conversations in a cafe to structured formal interviews in which the interviewer asks the same specific questions of a number of carefully chosen key informants. They can be conducted with individuals or groups, in all kinds of different places and circumstances. They're often the best sources of information, but they're also time-consuming and involve finding the right people and convincing them to consent to be interviewed, as well as finding (and sometimes training) good interviewers.

Interviews may include enlisting as sources of information others who've spent time learning about the community.  University researchers, staff and administrators of health and human service organizations, and activists may all have done considerable work to understand the character and inner workings of the community.  Take advantage of their findings if you can.  It may save you many hours of effort.

  • Surveys. There are various types of surveys. They can be written or oral, conducted with a selected small group -- usually a randomized sample that represents a larger population -- or with as many community members as possible. They can be sent through the mail, administered over the phone or in person, or given to specific groups (school classes, faith congregations, the Rotary Club). They're often fairly short, and ask for answers that are either yes-no, or that rate the survey-taker's opinion of a number of possibilities (typically on a scale that represents "agree strongly" to "disagree strongly" or "very favorable" to "very unfavorable.")  Surveys can, however, be much more comprehensive, with many questions, and can ask for more complex answers.
  • Direct or participant observation.  Often the best way to find out about the community is simply to observe. You can observe physical features, conditions in various areas, the interactions of people in different neighborhoods and circumstances, the amount of traffic, commercial activity, how people use various facilities and spaces, or the evidence of previous events or decisions. Participant observation means becoming part of the group or scene you're observing, so that you can see it from the inside.

Observation can take many forms.  In addition to simply going to a place and taking notes on what you see, you might use other techniques -- Photovoice, video, audio, simple photographs, drawings, etc.  Don't limit the ways in which you can record your observations and impressions.

Understanding the Community

Now let's consider what you might examine to understand and describe the community. You won't necessarily look for this information in the order given here, although it's a good idea to start with the first two.

The community's physical characteristics.

Get a map of the community and drive and/or walk around. (If the community isn't defined by geography, note and observe the areas where its members live, work, and gather.) Observe both the built and the natural environment. In the built environment, some things to pay attention to are:

  • The age, architecture, and condition of housing and other buildings. Some shabby or poorly-maintained housing may occupy good buildings that could be fixed up, for example -- that's important to know. Is there substandard housing in the community? Look for new construction, and new developments, and take note of where they are, and whether they're replacing existing housing or businesses or adding to it. (You might want to find out more about these. Are they controversial? Was there opposition to them, and how was it resolved? Does the community offer incentives to developers, and, if so, for what?)  Is housing separated by income or other factors, so that all low-income residents, for instance, or all North African immigrants seem to live in one area away from others? Are buildings generally in good condition, or are they dirty and run-down? Are there buildings that look like they might have historic significance, and are they kept up? Are most buildings accessible to people with disabilities?
  • Commercial areas.  Are there stores and other businesses in walking distance of residential areas or of public transportation for most members of the community? Do commercial buildings present windows and displays or blank walls to pedestrians? Is there foot traffic and activity in commercial areas, or do they seem deserted? Is there a good mix of local businesses, or nothing but chain stores? Are there theaters, places to hear music, a variety of restaurants, and other types of entertainment? Do many buildings include public spaces -- indoor or outdoor plazas where people can sit, for example? In general, are commercial areas and buildings attractive and well-maintained?
  • The types and location of industrial facilities. What kind of industry exists in the community? Does it seem to have a lot of environmental impact -- noise, air or water pollution, smells, heavy traffic? Is it located close to residential areas, and, if so, who lives there? Is there some effort to make industrial facilities attractive -- landscaping, murals or imaginative color schemes on the outside, etc?
  • Infrastructure.  What condition are streets in?  Do most streets, at least in residential and commercial areas, have sidewalks? Bike lanes? Are pedestrians shielded from traffic by trees, grass strips, and/or plantings? Are roads adequate for the traffic they bear? Are there foot bridges across busy highways and railroad tracks, or do they separate areas of the community and pose dangers for pedestrians? Is there adequate public transportation, with facilities for people with physical disabilities? Does it reach all areas of the community? Can most people gain access to the Internet if they have the equipment (i.e., computers or properly equipped cell phones)?

This is a topic that is ripe for examination. In many rural areas, particularly in developing countries, but often in the developed world as well, there is very little infrastructure.  Roads and bridges may be impassable at certain (or most) times of year, phone service and TV reception nonexistent, Internet access a distant dream. Public transportation in many places, if it exists at all, may take the form of a pickup truck or 20-year-old van that takes as many passengers as can squeeze into or onto the bed, passenger compartment, and roof. Is any of this on the government's or anyone else's radar as a situation that needs to be addressed? What is the general policy about services to rural and/or poor populations?  Answers to these and similar questions may both explain the situation (and the attitudes of the local population) and highlight a number of possible courses of action.

In the category of natural features, we can include both areas that have been largely left to nature, and "natural" spaces created by human intervention.

  • Topography. An area's topography is the shape of its landscape. Is the community largely hilly, largely flat, or does it incorporate areas of both? Is water -- rivers, creeks, lakes and ponds, canals, seashore -- a noticeable or important part of the physical character of the community? Who lives in what areas of the community?
  • Open space and greenery. Is there open space scattered throughout the community, or is it limited to one or a few areas? How much open space is there? Is it mostly man-made (parks, commons, campuses, sports fields), or is there wilderness or semi-wilderness? Does the community give the impression  of being green and leafy, with lots of trees and grass, or is it mostly concrete or dirt?
  • Air and water. Is the air reasonably clear and clean, or is there a blanket of smog? Does the air generally smell fresh, or are there industrial or other unpleasant odors? Do rivers, lakes, or other bodies of water appear clean? Do they seem to be used for recreation (boating, swimming, fishing)?

There is an overlap between the community's physical and social characteristics. Does the lay of the land make it difficult to get from one part of the community to another? (Biking, or in some cases even walking, is difficult in San Francisco, for example, because of the length and steepness of the hills.)  Are there clear social divisions that mirror the landscape -- all the fancy houses in the hills, all the low-income housing in the flats, for instance?

Studying the physical layout of the community will serve you not only as information, but as a guide for finding your way around, knowing what people are talking about when they refer to various areas and neighborhoods, and gaining a sense of the living conditions of any populations you're concerned with.

Community demographics.

Demographics are the facts about the population that you can find from census data and other similar statistical information. Some things you might like to know, besides the number of people in the community:

  • Gender
  • Racial and ethnic background
  • Age.  Numbers and percentages of the population in various age groups
  • Marital status
  • Family size
  • Education
  • Income
  • Employment - Both the numbers of people employed full and part-time, and the numbers of people in various types of work
  • Location - Knowing which groups live in which neighborhoods or areas can help to recruit participants in a potential effort or to decide where to target activities

In the U.S., most of this and other demographic information is available from the U.S. Census, from state and local government websites, or from other government agencies.  Depending on what issues and countries you're concerned with, some sources of information might be the U.S. Centers for Disease Control, the U.S. Department of Health and Human Services, similar websites in other countries, and the various agencies of the United Nations.

On many of these websites, notably the U.S. Census, various categories can be combined, so that you can, for example, find out the income levels in your community for African American women aged 25-34 with a high school education. If the website won't do it for you, it's fairly easy to trace the patterns yourself, thus giving you a much clearer picture of who community residents are and what their lives might be like.

Another extremely useful resource is County Health Rankings & Roadmaps, which provides rankings for nearly every county in the nation. The County Health Rankings model includes four types of health factors: health behaviors, clinical care, social and economic, and the physical environment. The County Health Rankings illustrate what we know when it comes to what’s making people sick or healthy, and the new County Health Roadmaps show what we can do to create healthier places to live, learn, work and play. These reports can help community leaders see that our environment influences how healthy we are and how long we live, and even what parts of our environment are most influential.

Community history.

This can be a complex topic. The "standard" history -- when the community was founded and by whom, how long it has existed, how people lived there in the past, its major sources of work, etc. -- can often be found in the local library or newspaper archives, or even in books or articles written for a larger audience. The less comfortable parts of that history, especially recent history -- discrimination, conflict, economic and/or political domination by a small group -- are may not be included, and are more likely to be found by talking to activists, journalists, and others who are concerned with those issues. You might also gain information by reading between the lines of old newspaper articles and tracking down people who were part of past conflicts or events.

If this all sounds a lot like investigative reporting, that's because it is.  You may not have the time or skills to do much of it, but talking to activists and journalists about recent history can be crucial.  Stepping into a community with an intervention or initiative without understanding the dynamics of community history can be a recipe for failure.

Community government and politics.

There are a number of ways to learn about the structure and operation of local government:

  • Go to open meetings of the city council, town boards, board of selectmen, or other bodies, as well as to public forums on proposed actions, laws, and regulations.  Such meetings will be announced in the local paper.

In most of the U.S., these meetings are public by state law, and must be announced in specific ways at least two days ahead.

  • Community bylaws and regulations are often available at the public library.
  • Make an appointment to talk to one or more local government officials.  Many hold regular office hours, and might actually take pleasure in explaining the workings of the local government.
  • Talk to community activists for a view of how the government actually operates, as opposed to how it's supposed to operate.
  • Read the local newspaper every day.

Reading the newspaper every day is a good idea in general if you're trying to learn about the community.  It will not only have stories about how the community operates, but will give you a sense of what's important to its readers, what kinds of activities the community engages in and views as significant, what the police do -- a picture of a large part of community life. Real estate ads will tell you about property values and the demand for housing, ads for services can help you identify the major businesses in town, and the ages and education levels of the people in the marriage and birth announcements can speak volumes about community values.  Newspaper archives can also reveal the stories that help you understand the emotions still surrounding events and issues that don't seem current.  The newspaper is an enormous reservoir of both direct and between-the-lines information.

As we all know, government isn't only about the rules and structures that hold it together. It's about people and their interactions...politics, in other words. The political climate, culture, and assumptions in a particular community often depend more on who elected and appointed officials are than on the limits or duties of their offices.

The politics of many communities embody the ideal of government working for the public good. In other communities, politics takes a back seat to economics, and politicians listen largely to those with economic power -- the CEO's, owners, and directors of large businesses and institutions.  In still others, the emphasis is on power itself, so that political decisions are made specifically to keep a particular party, group, or individual in control.

Obviously, only in the first case is the public well served. In the other situations, fairness and equity tend to go out the window and decisions favor the powerful. Understanding the politics of the community -- who has power, who the power brokers are, who actually influences the setting of policy, how decisions are made and by whom, how much difference public opinion makes -- is fundamental to an understanding of the community as a whole.

There's no formal way to get this information. Government officials may have very different interpretations of the political scene than activists or other community members. You'll have to talk to a variety of people, take a good look at recent political controversies and decisions (here's where newspaper archives can come in handy), and juggle some contradicting stories to get at the reality.

Institutions.

Community institutions, unless they are dysfunctional, can generally be viewed as assets. Finding them should be easy: as mentioned above, the Chamber of Commerce will probably have a list of them, the library will probably have one as well, the local newspaper will often list them, and they'll be in the phone book. 

They cover the spectrum of community life, including:

  • Offices of local, state, and federal government agencies (Welfare, Dept. of Agriculture, Office of Immigration, etc.)
  • Public libraries.
  • Religious institutions. Churches, synagogues, mosques.
  • Cultural institutions.  Museums, theaters, concert halls, etc. and the companies they support.  These may also encompass community theater and music companies run and staffed by community volunteer boards and performers.
  • Community centers.  Community centers may provide athletic, cultural, social, and other (yoga, support groups) activities for a variety of ages.
  • YMCA's and similar institutions.
  • Senior centers.
  • Hospitals and public health services.
  • Colleges and universities.
  • Public and private schools.
  • Public sports facilities. These might be both facilities for the direct use of the public -- community pools and athletic fields, for example -- or stadiums and arena where school, college, or professional teams play as entertainment.

Groups and organizations.

The groups and organizations that exist in the community, and their relative prestige and importance in community life, can convey valuable clues to the community's assumptions and attitudes. To some extent, you can find them in the same ways that you can find institutions, but the less formal ones you may be more likely to learn about through interviews and conversations. 

These groups can fall into a number of categories:

  • Health and human service organizations.  Known on the world stage as NGO's (Non-Governmental Organizations), these are the organizations that work largely with low-income people and populations at risk. They encompass free or sliding-scale health clinics, family planning programs, mental health centers, food pantries, homeless shelters, teen parent programs, youth outreach organizations, violence prevention programs, etc.
  • Advocacy organizations. These may also provide services, but generally in the form of legal help or advocacy with agencies to protect the rights of specific groups or to push for the provision of specific services. By and large, they advocate for recognition and services for populations with particular characteristics, or for more attention to be paid to particular issues.
  • Service clubs. Lions, Rotary, Kiwanis, Elks, Masons, etc.
  • Veterans' organizations. In the U.S., the American Legion and the Veterans of Foreign Wars are the major veterans' organizations, but many communities may have others as well.
  • Chamber of Commerce and other business organizations. Some of these may be oriented toward specific types of businesses, while others, like the Chamber, are more general.
  • Groups connected to institutions. Church youth or Bible study groups, school clubs, university student groups (e.g., Foreign Students' Association, community service groups).
  • Trade unions. These may be local, or branches of national or international unions.
  • Sports clubs or leagues. Enthusiasts of many sports organize local leagues that hold regular competitions, and that may compete as well with teams from other communities. In many rural areas, Fish and Game clubs may function as informal community centers.
  • Informal groups. Book clubs, garden clubs, parents' groups, etc.

Economics/employment.

Some of the information about economic issues can be found in public records, but some will come from interviews or conversations with business people, government officials, and activists, and some from observation. It's fairly easy to notice if one huge industrial plant dominates a community, for example, or if every third building appears to be a construction company. There are a number of questions you might ask yourself and others to help you understand the community's economic base and situation: What is the anchor of the community's tax base? Who are the major employers? Does the community have a particular business or business/industry category that underlies most of the jobs? Are there lots of locally-owned businesses and industries, or are most parts of larger corporations headquartered elsewhere?  Are there corporate headquarters in the community? Is there a good deal of office space, and is it empty or occupied?  Is there new development, and is the community attracting new business? What is the unemployment rate?

Social structure.

This may be the most difficult aspect of the community to understand, since it incorporates most of the others we've discussed, and is usually unspoken. People's answers to questions about it may ignore important points, either because they seem obvious to those who've lived with them for all or most of their lives, or because those things "just aren't talked about." Distrust or actual discrimination aimed at particular groups -- based on race, class, economics, or all three -- may be glossed over or never mentioned. The question of who wields the real power in the community is another that may rarely be answered, or at least not answered in the same way by a majority of community members. It's likely that it will take a number of conversations, some careful observation and some intuition as well to gain a real sense of the community's social structure.

Describing the Community

Once you've gathered the information you need, the next step is describing the community. This is not really separate from understanding the community: in the process of organizing and writing down your information, you'll be able to see better how it fits together, and can gain greater understanding.

There are many ways you can create a description of the community. The most obvious is simply to organize, record, and comment on your information by category:  physical description, government, institutions, etc. You can comment about what has changed in the community over time, what has stayed the same, and where you think the community might be going. You might also include an analysis of how the various categories interact, and how that all comes together to form the community that exists. That will give you and anyone else interested a reasonably clear and objective description of the community, as well as a sense of how you see it.

For a fuller picture, you could add photographs of some of the locations, people, conditions, or interactions you describe (perhaps as a Photovoice project), as well as charts or graphs of demographic or statistical information. For even more detail, you might compose a portrait in words of the community, using quotes from interviews and stories of community history to bring the description to life.

Given the availability of technology, you don't have to limit yourself to any specific format. Computers allow you to easily combine various media -- photos, graphics, animation, text, and audio, for example. The description could  add in or take the form of a video that includes a tour of the community, statements from and/or interviews with various community members (with their permission, of course), an audio voice-over, maps, etc.  A video or a more text-based description -- or both -- could then be posted to a website where it would be available to anyone interested.

Once you have a description put together, you might want to show it to some of the community members you talked to in the course of exploring the community. They can suggest other things you might include, correct errors of fact, and react to what they consider the accuracy or inaccuracy of your portrait and analysis of their community. With this feedback, you can then create a final version to use and to show to anyone interested. The point is to get as informative and accurate a picture of the community as possible that will serve as a basis for community assessment and any effort that grows out of it.

The last word here is that this shouldn't be the last community description you'll ever do. Communities reinvent themselves constantly, as new buildings and developments are put up and old ones torn down, as businesses move in and out, as populations shift -- both within the community and as people and groups move in and out -- and as economic, social, and political conditions change. You have to keep up with those changes, and that means updating your community description regularly.  As with most of the rest of the community building work described in the Community Tool Box, the work of understanding and describing the community is ongoing, for as long as you remain committed to the community itself.

In Summary

Understanding a community is crucial to being able to work in it. Failing to understand it will deny you credibility and make it difficult for you both to connect with community members and to negotiate the twists and turns of starting and implementing a community initiative or intervention. An extremely important part of any community assessment, therefore, is to start by finding out as much about the community as you can -- its physical and geographical characteristics, its culture, its government, and its assumptions. By combing through existing data, observing, and learning from community members, you can gain an overview of the community that will serve you well. Recording your findings and your analysis of them in a community description that you can refer to and update as needed will keep your understanding fresh and help others in your organization or with whom you collaborate.


Abstract

WSDL is an XML format for describing network services as a set of endpoints operating on messages containing either document-oriented or procedure-oriented information. The operations and messages are described abstractly, and then bound to a concrete network protocol and message format to define an endpoint. Related concrete endpoints are combined into abstract endpoints (services). WSDL is extensible to allow description of endpoints and their messages regardless of what message formats or network protocols are used to communicate, however, the only bindings described in this document describe how to use WSDL in conjunction with SOAP 1.1, HTTP GET/POST, and MIME.

Status

This document is a submission to the World Wide Web Consortium (see Submission Request, W3C Staff Comment) as a suggestion for describing services for the W3C XML Activity on XML Protocols. For a full list of all acknowledged Submissions, please see Acknowledged Submissions to W3C.

This draft represents the current thinking with regard to descriptions of services within Ariba, IBM and Microsoft.  It consolidates concepts found in NASSL, SCL, and SDL (earlier proposals in this space).

This document is a NOTE made available by the W3C for discussion only. Publication of this Note by W3C indicates no endorsement by W3C or the W3C Team, or any W3C Members. W3C has had no editorial control over the preparation of this Note. This document is a work in progress and may be updated, replaced, or rendered obsolete by other documents at any time.

A list of current W3C technical documents can be found at the Technical Reports page.

Table of Contents

1 Introduction.
1.1 WSDL Document Example
1.2 Notational Conventions
2 Service Definition
2.1 Document Structure
2.1.1 Document Naming and Linking
2.1.2 Authoring Style
2.1.3 Language Extensibility and Binding
2.1.4 Documentation
2.2 Types
2.3 Messages
2.3.1 Message Parts
2.3.2 Abstract vs. Concrete Messages
2.4 Port Types
2.4.1 One-way Operation
2.4.2 Request-response Operation.
2.4.3 Solicit-response Operation
2.4.4 Notification Operation
2.4.5 Names of Elements within an Operation
2.4.6 Parameter Order within an Operation
2.5 Bindings
2.6 Ports
2.7 Services
3 SOAP Binding
3.1 SOAP Examples
3.2 How the SOAP Binding Extends WSDL
3.3 soap:binding
3.4 soap:operation
3.5 soap:body
3.6 soap:fault
3.7 soap:header and soap:headerfault
3.8 soap:address
4 HTTP GET & POST Binding
4.1 HTTP GET/POST Examples
4.2 How the HTTP GET/POST Binding Extends WSDL
4.3 http:address
4.4 http:binding
4.5 http:operation
4.6 http:urlEncoded
4.7 http:urlReplacement
5 MIME Binding
5.1 MIME Binding example
5.2 How the MIME Binding extends WSDL
5.3 mime:content
5.4 mime:multipartRelated
5.5 soap:body
5.6 mime:mimeXml
6 References
A 1 Notes on URIs
A 1.1 XML namespaces & schema locations
A 1.2 Relative URIs
A 1.3 Generating URIs
A 2 Wire format for WSDL examples
A 2.1 Example 1
A 3 Location of Extensibility Elements
A 4 Schemas
A 4.1 WSDL Schema
A 4.2 SOAP Binding Schema
A 4.3 HTTP Binding Schema
A 4.4 MIME Binding Schema

1. Introduction

As communications protocols and message formats are standardized in the web community, it becomes increasingly possible and important to be able to describe the communications in some structured way. WSDL addresses this need by defining an XML grammar for describing network services as collections of communication endpoints capable of exchanging messages. WSDL service definitions provide documentation for distributed systems and serve as a recipe for automating the details involved in applications communication.

A WSDL document defines services as collections of network endpoints, or ports. In WSDL, the abstract definition of endpoints and messages is separated from their concrete network deployment or data format bindings. This allows the reuse of abstract definitions: messages, which are abstract descriptions of the data being exchanged, and port types which are abstract collections of operations. The concrete protocol and data format specifications for a particular port type constitutes a reusable binding. A port is defined by associating a network address with a reusable binding, and a collection of ports define a service. Hence, a WSDL document uses the following elements in the definition of network services:

  • Types– a container for data type definitions using some type system (such as XSD).
  • Message– an abstract, typed definition of the data being communicated.
  • Operation– an abstract description of an action supported by the service.
  • Port Type–an abstract set of operations supported by one or more endpoints.
  • Binding– a concrete protocol and data format specification for a particular port type.
  • Port– a single endpoint defined as a combination of a binding and a network address.
  • Service– a collection of related endpoints.

These elements are described in detail in Section 2. It is important to observe that WSDL does not introduce a new type definition language. WSDL recognizes the need for rich type systems for describing message formats, and supports the XML Schemas specification (XSD) [11] as its canonical type system. However, since it is unreasonable to expect a single type system grammar to be used to describe all message formats present and future, WSDL allows using other type definition languages via extensibility.

In addition, WSDL defines a common binding mechanism. This is used to attach a specific protocol or data format or structure to an abstract message, operation, or endpoint. It allows the reuse of abstract definitions.

In addition to the core service definition framework, this specification introduces specific binding extensions for the following protocols and message formats:

Although defined within this document, the above language extensions are layered on top of the core service definition framework. Nothing precludes the use of other binding extensions with WSDL.

1.2 WSDL Document Example

The following example shows the WSDL definition of a simple service providing stock quotes. The service supports a single operation called GetLastTradePrice, which is deployed using the SOAP 1.1 protocol over HTTP. The request takes a ticker symbol of type string, and returns the price as a float. A detailed description of the elements used in this definition can be found in Section 2 (core language) and Section 3 (SOAP binding).

This example uses a fixed XML format instead of the SOAP encoding (for an example using the SOAP encoding, see Example 4).

Example 1 SOAP 1.1 Request/Response via HTTP

<?xml version="1.0"?> <definitions name="StockQuote" targetNamespace="http://example.com/stockquote.wsdl" xmlns:tns="http://example.com/stockquote.wsdl" xmlns:xsd1="http://example.com/stockquote.xsd" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns="http://schemas.xmlsoap.org/wsdl/"> <types> <schema targetNamespace="http://example.com/stockquote.xsd" xmlns="http://www.w3.org/2000/10/XMLSchema"> <element name="TradePriceRequest"> <complexType> <all> <element name="tickerSymbol" type="string"/> </all> </complexType> </element> <element name="TradePrice"> <complexType> <all> <element name="price" type="float"/> </all> </complexType> </element> </schema> </types> <message name="GetLastTradePriceInput"> <part name="body" element="xsd1:TradePriceRequest"/> </message> <message name="GetLastTradePriceOutput"> <part name="body" element="xsd1:TradePrice"/> </message> <portType name="StockQuotePortType"> <operation name="GetLastTradePrice"> <input message="tns:GetLastTradePriceInput"/> <output message="tns:GetLastTradePriceOutput"/> </operation> </portType> <binding name="StockQuoteSoapBinding" type="tns:StockQuotePortType"> <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/> <operation name="GetLastTradePrice"> <soap:operation soapAction="http://example.com/GetLastTradePrice"/> <input> <soap:body use="literal"/> </input> <output> <soap:body use="literal"/> </output> </operation> </binding> <service name="StockQuoteService"> <documentation>My first service</documentation> <port name="StockQuotePort" binding="tns:StockQuoteBinding"> <soap:address location="http://example.com/stockquote"/> </port> </service> </definitions>

1.2 Notational Conventions

1. The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC-2119 [2].

2. The following namespace prefixes are used throughout this document:

prefixnamespace URI definition
wsdlhttp://schemas.xmlsoap.org/wsdl/WSDL namespace for WSDL framework.
soaphttp://schemas.xmlsoap.org/wsdl/soap/WSDL namespace for WSDL SOAP binding.
httphttp://schemas.xmlsoap.org/wsdl/http/WSDL namespace for WSDL HTTP GET & POST binding.
mimehttp://schemas.xmlsoap.org/wsdl/mime/WSDL namespace for WSDL MIME binding.
soapenchttp://schemas.xmlsoap.org/soap/encoding/Encoding namespace as defined by SOAP 1.1 [8].
soapenvhttp://schemas.xmlsoap.org/soap/envelope/Envelope namespace as defined by SOAP 1.1 [8].
xsihttp://www.w3.org/2000/10/XMLSchema-instanceInstance namespace as defined by XSD [10].
xsdhttp://www.w3.org/2000/10/XMLSchemaSchema namespace as defined by XSD [10].
tns(various)The “this namespace” (tns) prefix is used as a convention to refer to the current document.
(other)(various)All other namespace prefixes are samples only. In particular, URIs starting with “http://example.com” represent some application-dependent or context-dependent URI [4].

3. This specification uses an informal syntax to describe the XML grammar of a WSDL document:

  • The syntax appears as an XML instance, but the values indicate the data types instead of values.
  • Characters are appended to elements and attributes as follows: "?" (0 or 1), "*" (0 or more), "+" (1 or more).
  • Elements names ending in "…" (such as <element…/> or <element…>) indicate that elements/attributes irrelevant to the context are being omitted.
  • Grammar in bold has not been introduced earlier in the document, or is of particular interest in an example.
  • <-- extensibility element --> is a placeholder for elements from some "other" namespace (like ##other in XSD).
  • The XML namespace prefixes (defined above) are used to indicate the namespace of the element being defined.
  • Examples starting with <?xml contain enough information to conform to this specification; others examples are fragments and require additional information to be specified in order to conform.

XSD schemas are provided as a formal definition of WSDL grammar (see section A4).

2. Service Definition

This section describes the core elements of the WSDL language. Binding extensions for SOAP, HTTP and MIME are included in Sections 3, 4 and 5.

2.1 WSDL Document Structure

A WSDL document is simply a set of definitions. There is a definitions element at the root, and definitions inside. The grammar is as follows:

<wsdl:definitions name="nmtoken"? targetNamespace="uri"?> <import namespace="uri" location="uri"/>* <wsdl:documentation .... /> ? <wsdl:types> ? <wsdl:documentation .... />? <xsd:schema .... />* <-- extensibility element --> * </wsdl:types> <wsdl:message name="nmtoken"> * <wsdl:documentation .... />? <part name="nmtoken" element="qname"? type="qname"?/> * </wsdl:message> <wsdl:portType name="nmtoken">* <wsdl:documentation .... />? <wsdl:operation name="nmtoken">* <wsdl:documentation .... /> ? <wsdl:input name="nmtoken"? message="qname">? <wsdl:documentation .... /> ? </wsdl:input> <wsdl:output name="nmtoken"? message="qname">? <wsdl:documentation .... /> ? </wsdl:output> <wsdl:fault name="nmtoken" message="qname"> * <wsdl:documentation .... /> ? </wsdl:fault> </wsdl:operation> </wsdl:portType> <wsdl:binding name="nmtoken" type="qname">* <wsdl:documentation .... />? <-- extensibility element --> * <wsdl:operation name="nmtoken">* <wsdl:documentation .... /> ? <-- extensibility element --> * <wsdl:input> ? <wsdl:documentation .... /> ? <-- extensibility element --> </wsdl:input> <wsdl:output> ? <wsdl:documentation .... /> ? <-- extensibility element --> * </wsdl:output> <wsdl:fault name="nmtoken"> * <wsdl:documentation .... /> ? <-- extensibility element --> * </wsdl:fault> </wsdl:operation> </wsdl:binding> <wsdl:service name="nmtoken"> * <wsdl:documentation .... />? <wsdl:port name="nmtoken" binding="qname"> * <wsdl:documentation .... /> ? <-- extensibility element --> </wsdl:port> <-- extensibility element --> </wsdl:service> <-- extensibility element --> * </wsdl:definitions>

Services are defined using six major elements:

  • types, which provides data type definitions used to describe the messages exchanged.
  • message, which represents an abstract definition of the data being transmitted. A message consists of logical parts, each of which is associated with a definition within some type system.
  • portType, which is a set of abstract operations. Each operation refers to an input message and output messages.
  • binding, which specifies concrete protocol and data format specifications for the operations and messages defined by a particular portType.
  • port, which specifies an address for a binding, thus defining a single communication endpoint.
  • service, which is used to aggregate a set of related ports.

These elements will be described in detail in Sections 2.2 to 2.7. In the rest of this section we describe the rules introduced by WSDL for naming documents, referencing document definitions, using language extensions and adding contextual documentation.

2.1.1 Document Naming and Linking

WSDL documents can be assigned an optional name attribute of type NCNAME that serves as a lightweight form of documentation. Optionally, a targetNamespace attribute of type URI may be specified. The URI MUST NOT be a relative URI.

WSDL allows associating a namespace with a document location using an import statement:

<definitions .... > <import namespace="uri" location="uri"/> * </definitions>

A reference to a WSDL definition is made using a QName. The following types of definitions contained in a WSDL document may be referenced:

  • WSDL definitions: service, port, message, bindings, and portType
  • Other definitions: if additional definitions are added via extensibility, they SHOULD use QName linking.

Each WSDL definition type listed above has its own name scope (i.e. port names and message names never conflict). Names within a name scope MUST be unique within the WSDL document.

The resolution of QNames in WSDL is similar to the resolution of QNames described by the XML Schemas specification [11].

2.1.2 Authoring Style

The use of the import element allows the separation of the different elements of a service definition into independent documents, which can then be imported as needed. This technique helps writing clearer service definitions, by separating the definitions according to their level of abstraction. It also maximizes the ability to reuse service definitions of all kinds. As a result, WSDL documents structured in this way are easier to use and maintain. Example 2 below shows how to use this authoring style to define the service presented in Example 1. Here we separate the definitions in three documents: data type definitions, abstract definitions, and specific service bindings. The use of this mechanism is of course not limited to the definitions explicitly presented in the example, which uses only language elements defined in this specification. Other types of definitions based on additional language extensions can be encoded and reused in a similar fashion.

Example 2. Alternative authoring style for the service in Example 1.

http://example.com/stockquote/stockquote.xsd

<?xml version="1.0"?> <schema targetNamespace="http://example.com/stockquote/schemas" xmlns="http://www.w3.org/2000/10/XMLSchema"> <element name="TradePriceRequest"> <complexType> <all> <element name="tickerSymbol" type="string"/> </all> </complexType> </element> <element name="TradePrice"> <complexType> <all> <element name="price" type="float"/> </all> </complexType> </element> </schema>

http://example.com/stockquote/stockquote.wsdl

<?xml version="1.0"?> <definitions name="StockQuote" targetNamespace="http://example.com/stockquote/definitions" xmlns:tns="http://example.com/stockquote/definitions" xmlns:xsd1="http://example.com/stockquote/schemas" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns="http://schemas.xmlsoap.org/wsdl/"> <import namespace="http://example.com/stockquote/schemas" location="http://example.com/stockquote/stockquote.xsd"/> <message name="GetLastTradePriceInput"> <part name="body" element="xsd1:TradePriceRequest"/> </message> <message name="GetLastTradePriceOutput"> <part name="body" element="xsd1:TradePrice"/> </message> <portType name="StockQuotePortType"> <operation name="GetLastTradePrice"> <input message="tns:GetLastTradePriceInput"/> <output message="tns:GetLastTradePriceOutput"/> </operation> </portType> </definitions>

http://example.com/stockquote/stockquoteservice.wsdl

<?xml version="1.0"?> <definitions name="StockQuote" targetNamespace="http://example.com/stockquote/service" xmlns:tns="http://example.com/stockquote/service" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:defs="http://example.com/stockquote/definitions" xmlns="http://schemas.xmlsoap.org/wsdl/"> <import namespace="http://example.com/stockquote/definitions" location="http://example.com/stockquote/stockquote.wsdl"/> <binding name="StockQuoteSoapBinding" type="defs:StockQuotePortType"> <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/> <operation name="GetLastTradePrice"> <soap:operation soapAction="http://example.com/GetLastTradePrice"/> <input> <soap:body use="literal"/> </input> <output> <soap:body use="literal"/> </output> </operation> </binding> <service name="StockQuoteService"> <documentation>My first service</documentation> <port name="StockQuotePort" binding="tns:StockQuoteBinding"> <soap:address location="http://example.com/stockquote"/> </port> </service> </definitions>

2.1.3 Language Extensibility and Binding

In WSDL the term binding refers to the process associating protocol or data format information with an abstract entity like a message, operation, or portType. WSDL allows elements representing a specific technology (referred to here as extensibility elements) under various elements defined by WSDL. These points of extensibility are typically used to specify binding information for a particular protocol or message format, but are not limited to such use. Extensibility elements MUST use an XML namespace different from that of WSDL. The specific locations in the document where extensibility elements can appear are described in detail in section A3.

Extensibility elements are commonly used to specify some technology specific binding. To distinguish whether the semantic of the technology specific binding is required for communication or optional, extensibility elements MAY place a wsdl:required attribute of type boolean on the element. The default value for required is false. The required attribute is defined in the namespace "http://schemas.xmlsoap.org/wsdl/".

Extensibility elements allow innovation in the area of network and message protocols without having to revise the base WSDL specification. WSDL recommends that specifications defining such protocols also define any necessary WSDL extensions used to describe those protocols or formats.

See Sections 3, 4, and 5 for examples of extensibility elements defined as part of the base WSDL specification.

2.1.4 Documentation

WSDL uses the optional wsdl:document element as a container for human readable documentation. The content of the element is arbitrary text and elements ("mixed" in XSD). The documentation element is allowed inside any WSDL language element.

2.2 Types

The types element encloses data type definitions that are relevant for the exchanged messages. For maximum interoperability and platform neutrality, WSDL prefers the use of XSD as the canonical type system, and treats it as the intrinsic type system.

<definitions .... > <types> <xsd:schema .... />* </types> </definitions>

The XSD type system can be used to define the types in a message regardless of whether or not the resulting wire format is actually XML, or whether the resulting XSD schema validates the particular wire format. This is especially interesting if there will be multiple bindings for the same message, or if there is only one binding but that binding type does not already have a type system in widespread use. In these cases, the recommended approach for encoding abstract types using XSD is as follows:

  • Use element form (not attribute).
  • Don't include attributes or elements that are peculiar to the wire encoding (e.g. have nothing to do with the abstract content of the message). Some examples are soap:root, soap:encodingStyle, xmi:id, xmi:name.
  • Array types should extend the Array type defined in the SOAP v1.1 encoding schema (http://schemas.xmlsoap.org/soap/encoding/) (regardless of whether the resulting form actually uses the encoding specified in Section 5 of the SOAP v1.1 document). Use the name ArrayOfXXX for array types (where XXX is the type of the items in the array).  The type of the items in the array and the array dimensions are specified by using a default value for the soapenc:arrayType attribute.  At the time of this writing, the XSD specification does not have a mechanism for specifying the default value of an attribute which contains a QName value.  To overcome this limitation, WSDL introduces the arrayType attribute (from namespace http://schemas.xmlsoap.org/wsdl/) which has the semantic of providing the default value.  If XSD is revised to support this functionality, the revised mechanism SHOULD be used in favor of the arrayType attribute defined by WSDL.
  • Use the xsd:anyType type to represent a field/parameter which can have any type. 

However, since it is unreasonable to expect a single type system grammar can be used to describe all abstract types present and future, WSDL allows type systems to be added via extensibility elements. An extensibility element may appear under the types element to identify the type definition system being used and to provide an XML container element for the type definitions. The role of this element can be compared to that of the schema element of the XML Schema language.

<definitions .... > <types> <-- type-system extensibility element --> * </types> </definitions>

2.3 Messages

Messages consist of one or more logical parts. Each part is associated with a type from some type system using a message-typing attribute. The set of message-typing attributes is extensible. WSDL defines several such message-typing attributes for use with XSD:

  • element. Refers to an XSD element using a QName.
  • type. Refers to an XSD simpleType or complexType using a QName.

Other message-typing attributes may be defined as long as they use a namespace different from that of WSDL. Binding extensibility elements may also use message-typing attributes.

The syntax for defining a message is as follows. The message-typing attributes (which may vary depending on the type system used) are shown in bold.

<definitions .... > <message name="nmtoken"> * <part name="nmtoken" element="qname"? type="qname"?/> * </message> </definitions>

The message name attribute provides a unique name among all messages defined within the enclosing WSDL document.

The part name attribute provides a unique name among all the parts of the enclosing message.

2.3.1 Message Parts

Parts are a flexible mechanism for describing the logical abstract content of a message. A binding may reference the name of a part in order to specify binding-specific information about the part. For example, if defining a message for use with RPC, a part MAY represent a parameter in the message. However, the bindings must be inspected in order to determine the actual meaning of the part.

Multiple part elements are used if the message has multiple logical units. For example, the following message consists of a Purchase Order and an Invoice.

<definitions .... > <types> <schema .... > <element name="PO" type="tns:POType"/> <complexType name="POType"> <all> <element name="id" type="string/> <element name="name" type="string"/> <element name="items"> <complexType> <all> <element name="item" type="tns:Item" minOccurs="0" maxOccurs="unbounded"/> </all> </complexType> </element> </all> </complexType> <complexType name="Item"> <all> <element name="quantity" type="int"/> <element name="product" type="string"/> </all> </complexType> <element name="Invoice" type="tns:InvoiceType"/> <complexType name="InvoiceType"> <all> <element name="id" type="string"/> </all> </complexType> </schema> </types> <message name="PO"> <part name="po" element="tns:PO"/> <part name="invoice" element="tns:Invoice"/> </message> </definitions>

However, if the message contents are sufficiently complex, then an alternative syntax may be used to specify the composite structure of the message using the type system directly. In this usage, only one part may be specified.  In the following example, the body is either a purchase order, or a set of invoices.  

<definitions .... > <types> <schema .... > <complexType name="POType"> <all> <element name="id" type="string/> <element name="name" type="string"/> <element name="items"> <complexType> <all> <element name="item" type="tns:Item" minOccurs="0" maxOccurs="unbounded"/> </all> </complexType> </element> </all> </complexType> <complexType name="Item"> <all> <element name="quantity" type="int"/> <element name="product" type="string"/> </all> </complexType> <complexType name="InvoiceType"> <all> <element name="id" type="string"/> </all> </complexType> <complexType name="Composite"> <choice> <element name="PO" minOccurs="1" maxOccurs="1" type="tns:POType"/> <element name="Invoice" minOccurs="0" maxOccurs="unbounded" type="tns:InvoiceType"/> </choice> </complexType> </schema> </types> <message name="PO"> <part name="composite" type="tns:Composite"/> </message> </definitions>

2.3.2 Abstract vs. Concrete Messages

Message definitions are always considered to be an abstract definition of the message content. A message binding describes how the abstract content is mapped into a concrete format. However, in some cases, the abstract definition may match the concrete representation very closely or exactly for one or more bindings, so those binding(s) will supply little or no mapping information. However, another binding of the same message definition may require extensive mapping information. For this reason, it is not until the binding is inspected that one can determine "how abstract" the message really is.

2.4 Port Types

A port type is a named set of abstract operations and the abstract messages involved.

<wsdl:definitions .... > <wsdl:portType name="nmtoken"> <wsdl:operation name="nmtoken" .... /> * </wsdl:portType> </wsdl:definitions>

The port type name attribute provides a unique name among all port types defined within in the enclosing WSDL document.

An operation is named via the name attribute.

WSDL has four transmission primitives that an endpoint can support:

  • One-way. The endpoint receives a message.
  • Request-response. The endpoint receives a message, and sends a correlated message.
  • Solicit-response. The endpoint sends a message, and receives a correlated message.
  • Notification. The endpoint sends a message.

WSDL refers to these primitives as operations. Although request/response or solicit/response can be modeled abstractly using two one-way messages, it is useful to model these as primitive operation types because:

  • They are very common.
  • The sequence can be correlated without having to introduce more complex flow information.
  • Some endpoints can only receive messages if they are the result of a synchronous request response.
  • A simple flow can algorithmically be derived from these primitives at the point when flow definition is desired.

Although request/response or solicit/response are logically correlated in the WSDL document, a given binding describes the concrete correlation information. For example, the request and response messages may be exchanged as part of one or two actual network communications.

Although the base WSDL structure supports bindings for these four transmission primitives, WSDL only defines bindings for the One-way and Request-response primitives.  It is expected that specifications that define the protocols for Solicit-response or Notification would also include WSDL binding extensions that allow use of these primitives.

Operations refer to the messages involved using the message attribute of type QName. This attribute follows the rules defined by WSDL for linking (see section 2.1.2).

2.4.1 One-way Operation

The grammar for a one-way operation is:

<wsdl:definitions .... > <wsdl:portType .... > * <wsdl:operation name="nmtoken"> <wsdl:input name="nmtoken"? message="qname"/> </wsdl:operation> </wsdl:portType > </wsdl:definitions>

The input element specifies the abstract message format for the one-way operation.

2.4.2 Request-response Operation

The grammar for a request-response operation is:

<wsdl:definitions .... > <wsdl:portType .... > * <wsdl:operation name="nmtoken" parameterOrder="nmtokens"> <wsdl:input name="nmtoken"? message="qname"/> <wsdl:output name="nmtoken"? message="qname"/> <wsdl:fault name="nmtoken" message="qname"/>* </wsdl:operation> </wsdl:portType > </wsdl:definitions>

The input and output elements specify the abstract message format for the request and response, respectively. The optional fault elements specify the abstract message format for any error messages that may be output as the result of the operation (beyond those specific to the protocol).

Note that a request-response operation is an abstract notion; a particular binding must be consulted to determine how the messages are actually sent: within a single communication (such as a HTTP request/response), or as two independent communications (such as two HTTP requests).

2.4.3 Solicit-response Operation

The grammar for a solicit-response operation is:

<wsdl:definitions .... > <wsdl:portType .... > * <wsdl:operation name="nmtoken" parameterOrder="nmtokens"> <wsdl:output name="nmtoken"? message="qname"/> <wsdl:input name="nmtoken"? message="qname"/> <wsdl:fault name="nmtoken" message="qname"/>* </wsdl:operation> </wsdl:portType > </wsdl:definitions>

The output and input elements specify the abstract message format for the solicited request and response, respectively. The optional fault elements specify the abstract message format for any error messages that may be output as the result of the operation (beyond those specific to the protocol).

Note that a solicit-response operation is an abstract notion; a particular binding must be consulted to determine how the messages are actually sent: within a single communication (such as a HTTP request/response), or as two independent communications (such as two HTTP requests).

2.4.4 Notification Operation

The grammar for a notification operation is:

<wsdl:definitions .... > <wsdl:portType .... > * <wsdl:operation name="nmtoken"> <wsdl:output name="nmtoken"? message="qname"/> </wsdl:operation> </wsdl:portType > </wsdl:definitions>

The output element specifies the abstract message format for the notification operation.

2.4.5 Names of Elements within an Operation

The name attribute of the input and output elements provides a unique name among all input and output elements within the enclosing port type.

In order to avoid having to name each input and output element within an operation, WSDL provides some default values based on the operation name. If the name attribute is not specified on a one-way or notification message, it defaults to the name of the operation. If the name attribute is not specified on the input or output messages of a request-response or solicit-response operation, the name defaults to the name of the operation with "Request"/"Solicit" or "Response" appended, respectively.

Each fault element must be named to allow a binding to specify the concrete format of the fault message. The name of the fault element is unique within the set of faults defined for the operation.

2.4.6 Parameter Order within an Operation

Operations do not specify whether they are to be used with RPC-like bindings or not. However, when using an operation with an RPC-binding, it is useful to be able to capture the original RPC function signature. For this reason, a request-response or solicit-response operation MAY specify a list of parameter names via the parameterOrder attribute (of type nmtokens). The value of the attribute is a list of message part names separated by a single space. The value of the parameterOrder attribute MUST follow the following rules:

  • The part name order reflects the order of the parameters in the RPC signature
  • The return value part is not present in the list
  • If a part name appears in both the input and output message, it is an in/out parameter
  • If a part name appears in only the input message, it is an in parameter
  • If a part name appears in only the output message, it is an out parameter

Note that this information serves as a "hint" and may safely be ignored by those not concerned with RPC signatures. Also, it is not required to be present, even if the operation is to be used with an RPC-like binding.

2.5 Bindings

A binding defines message format and protocol details for operations and messages defined by a particular portType. There may be any number of bindings for a given portType. The grammar for a binding is as follows:

<wsdl:definitions .... > <wsdl:binding name="nmtoken" type="qname"> * <-- extensibility element (1) --> * <wsdl:operation name="nmtoken"> * <-- extensibility element (2) --> * <wsdl:input name="nmtoken"? > ? <-- extensibility element (3) --> </wsdl:input> <wsdl:output name="nmtoken"? > ? <-- extensibility element (4) --> * </wsdl:output> <wsdl:fault name="nmtoken"> * <-- extensibility element (5) --> * </wsdl:fault> </wsdl:operation> </wsdl:binding> </wsdl:definitions>

The name attribute provides a unique name among all bindings defined within in the enclosing WSDL document.

A binding references the portType that it binds using the type attribute. This QName value follows the linking rules defined by WSDL (see section 2.1.2).

Binding extensibility elements are used to specify the concrete grammar for the input (3), output (4), and fault messages (5). Per-operation binding information (2) as well as per-binding information (1) may also be specified.

An operation element within a binding specifies binding information for the operation with the same name within the binding's portType. Since operation names are not required to be unique (for example, in the case of overloading of method names), the name attribute in the operation binding element might not be enough to uniquely identify an operation. In that case, the correct operation should be identified by providing the name attributes of the corresponding wsdl:input and wsdl:output elements.

A binding MUST specify exactly one protocol.

A binding MUST NOT specify address information.

2.6 Ports

A port defines an individual endpoint by specifying a single address for a binding.

<wsdl:definitions .... > <wsdl:service .... > * <wsdl:port name="nmtoken" binding="qname"> * <-- extensibility element (1) --> </wsdl:port> </wsdl:service> </wsdl:definitions>

The name attribute provides a unique name among all ports defined within in the enclosing WSDL document.

The binding attribute (of type QName) refers to the binding using the linking rules defined by WSDL (see Section 2.1.2).

Binding extensibility elements (1) are used to specify the address information for the port.

A port MUST NOT specify more than one address.

A port MUST NOT specify any binding information other than address information.

2.7 Services

A service groups a set of related ports together:

<wsdl:definitions .... > <wsdl:service name="nmtoken"> * <wsdl:port .... />* </wsdl:service> </wsdl:definitions>

The name attribute provides a unique name among all services defined within in the enclosing WSDL document.

Ports within a service have the following relationship:

  • None of the ports communicate with each other (e.g. the output of one port is not the input of another).
  • If a service has several ports that share a port type, but employ different bindings or addresses, the ports are alternatives. Each port provides semantically equivalent behavior (within the transport and message format limitations imposed by each binding). This allows a consumer of a WSDL document to choose particular port(s) to communicate with based on some criteria (protocol, distance, etc.).
  • By examining it's ports, we can determine a service's port types. This allows a consumer of a WSDL document to determine if it wishes to communicate to a particular service based whether or not it supports several port types. This is useful if there is some implied relationship between the operations of the port types, and that the entire set of port types must be present in order to accomplish a particular task.

3. SOAP Binding

WSDL includes a binding for SOAP 1.1 endpoints, which supports the specification of the following protocol specific information:

  • An indication that a binding is bound to the SOAP 1.1 protocol
  • A way of specifying an address for a SOAP endpoint.
  • The URI for the SOAPAction HTTP header for the HTTP binding of SOAP
  • A list of definitions for Headers that are transmitted as part of the SOAP Envelope

This binding grammar it is not an exhaustive specification since the set of SOAP bindings is evolving. Nothing precludes additional SOAP bindings to be derived from portions of this grammar. For example:

  • SOAP bindings that do not employ a URI addressing scheme may substitute another addressing scheme by replacing the soap:address element defined in section 3.8.
  • SOAP bindings that do not require a SOAPAction omit the soapAction attribute defined in section 3.4.

3.1 SOAP Examples

In the following example, a SubscribeToQuotes SOAP 1.1 one-way message is sent to a StockQuote service via a SMTP binding. The request takes a ticker symbol of type string, and includes a header defining the subscription URI.

Example 3. SOAP binding of one-way operation over SMTP using a SOAP Header

<?xml version="1.0"?> <definitions name="StockQuote" targetNamespace="http://example.com/stockquote.wsdl" xmlns:tns="http://example.com/stockquote.wsdl" xmlns:xsd1="http://example.com/stockquote.xsd" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns="http://schemas.xmlsoap.org/wsdl/"> <message name="SubscribeToQuotes"> <part name="body" element="xsd1:SubscribeToQuotes"/> <part name="subscribeheader" element="xsd1:SubscriptionHeader"/> </message> <portType name="StockQuotePortType"> <operation name="SubscribeToQuotes"> <input message="tns:SubscribeToQuotes"/> </operation> </portType> <binding name="StockQuoteSoap" type="tns:StockQuotePortType"> <soap:binding style="document" transport="http://example.com/smtp"/> <operation name="SubscribeToQuotes"> <input message="tns:SubscribeToQuotes"> <soap:body parts="body" use="literal"/> <soap:header message="tns:SubscribeToQuotes" part="subscribeheader" use="literal"/> </input> </operation> </binding> <service name="StockQuoteService"> <port name="StockQuotePort" binding="tns:StockQuoteSoap"> <soap:address location="mailto:subscribe@example.com"/> </port> </service> <types> <schema targetNamespace="http://example.com/stockquote.xsd" xmlns="http://www.w3.org/2000/10/XMLSchema"> <element name="SubscribeToQuotes"> <complexType> <all> <element name="tickerSymbol" type="string"/> </all> </complexType> </element> <element name="SubscriptionHeader" type="uriReference"/> </schema> </types> </definitions>

This example describes that a GetTradePrice SOAP 1.1 request may be sent to a StockQuote service via the SOAP 1.1 HTTP binding. The request takes a ticker symbol of type string, a time of type timeInstant, and returns the price as a float in the SOAP response.

Example 4. SOAP binding of request-response RPC operation over HTTP

<?xml version="1.0"?> <definitions name="StockQuote" targetNamespace="http://example.com/stockquote.wsdl" xmlns:tns="http://example.com/stockquote.wsdl" xmlns:xsd="http://www.w3.org/2000/10/XMLSchema" xmlns:xsd1="http://example.com/stockquote.xsd" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns="http://schemas.xmlsoap.org/wsdl/"> <message name="GetTradePriceInput"> <part name="tickerSymbol" element="xsd:string"/> <part name="time" element="xsd:timeInstant"/> </message> <message name="GetTradePriceOutput"> <part name="result" type="xsd:float"/> </message> <portType name="StockQuotePortType"> <operation name="GetTradePrice"> <input message="tns:GetTradePriceInput"/> <output message="tns:GetTradePriceOutput"/> </operation> </portType> <binding name="StockQuoteSoapBinding" type="tns:StockQuotePortType"> <soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/> <operation name="GetTradePrice"> <soap:operation soapAction="http://example.com/GetTradePrice"/> <input> <soap:body use="encoded" namespace="http://example.com/stockquote" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/> </input> <output> <soap:body use="encoded" namespace="http://example.com/stockquote" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/> </output> </operation>> </binding> <service name="StockQuoteService"> <documentation>My first service</documentation> <port name="StockQuotePort" binding="tns:StockQuoteBinding"> <soap:address location="http://example.com/stockquote"/> </port> </service> </definitions>

This example describes that a GetTradePrices SOAP 1.1 request may be sent to a StockQuote service via the SOAP 1.1 HTTP binding. The request takes a stock quote symbol string, an application defined TimePeriod structure containing a start and end time and returns an array of stock prices recorded by the service within that period of time, as well as the frequency at which they were recorded as the SOAP response.  The RPC signature that corresponds to this service has in parameters tickerSymbol and timePeriod followed by the output parameter frequency, and returns an array of floats.

Example 5. SOAP binding of request-response RPC operation over HTTP

<?xml version="1.0"?> <definitions name="StockQuote" targetNamespace="http://example.com/stockquote.wsdl" xmlns:tns="http://example.com/stockquote.wsdl" xmlns:xsd="http://www.w3.org/2000/10/XMLSchema" xmlns:xsd1="http://example.com/stockquote/schema" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns="http://schemas.xmlsoap.org/wsdl/"> <types> <schema targetNamespace="http://example.com/stockquote/schema" xmlns="http://www.w3.org/2000/10/XMLSchema"> <complexType name="TimePeriod"> <all> <element name="startTime" type="xsd:timeInstant"/> <element name="endTime" type="xsd:timeInstant"/> </all> </complexType> <complexType name="ArrayOfFloat"> <complexContent> <restriction base="soapenc:Array"> <attribute ref="soapenc:arrayType" wsdl:arrayType="xsd:float[]"/> </restriction> </complexContent> </complexType> </schema> </types> <message name="GetTradePricesInput"> <part name="tickerSymbol" element="xsd:string"/> <part name="timePeriod" element="xsd1:TimePeriod"/> </message> <message name="GetTradePricesOutput"> <part name="result" type="xsd1:ArrayOfFloat"/> <part name="frequency" type="xsd:float"/> </message> <portType name="StockQuotePortType"> <operation name="GetLastTradePrice" parameterOrder="tickerSymbol timePeriod frequency"> <input message="tns:GetTradePricesInput"/> <output message="tns:GetTradePricesOutput"/> </operation> </portType> <binding name="StockQuoteSoapBinding" type="tns:StockQuotePortType"> <soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/> <operation name="GetTradePrices"> <soap:operation soapAction="http://example.com/GetTradePrices"/> <input> <soap:body use="encoded" namespace="http://example.com/stockquote" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/> </input> <output> <soap:body use="encoded" namespace="http://example.com/stockquote" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/> </output> </operation>> </binding> <service name="StockQuoteService"> <documentation>My first service</documentation> <port name="StockQuotePort" binding="tns:StockQuoteBinding"> <soap:address location="http://example.com/stockquote"/> </port> </service> </definitions>

3.2 How the SOAP Binding Extends WSDL

The SOAP Binding extends WSDL with the following extension elements:

<definitions .... > <binding .... > <soap:binding style="rpc|document" transport="uri"> <operation .... > <soap:operation soapAction="uri"? style="rpc|document"?>? <input> <soap:body parts="nmtokens"? use="literal|encoded" encodingStyle="uri-list"? namespace="uri"?> <soap:header message="qname" part="nmtoken" use="literal|encoded" encodingStyle="uri-list"? namespace="uri"?>* <soap:headerfault message="qname" part="nmtoken" use="literal|encoded" encodingStyle="uri-list"? namespace="uri"?/>* <soap:header> </input> <output> <soap:body parts="nmtokens"? use="literal|encoded" encodingStyle="uri-list"? namespace="uri"?> <soap:header message="qname" part="nmtoken" use="literal|encoded" encodingStyle="uri-list"? namespace="uri"?>* <soap:headerfault message="qname" part="nmtoken" use="literal|encoded" encodingStyle="uri-list"? namespace="uri"?/>* <soap:header> </output> <fault>* <soap:fault name="nmtoken" use="literal|encoded" encodingStyle="uri-list"? namespace="uri"?> </fault> </operation> </binding> <port .... > <soap:address location="uri"/> </port> </definitions>

Each extension element of the SOAP binding is covered in subsequent sections.

3.3 soap:binding

The purpose of the SOAP binding element is to signify that the binding is bound to the SOAP protocol format: Envelope, Header and Body. This element makes no claims as to the encoding or format of the message (e.g. that it necessarily follows section 5 of the SOAP 1.1 specification).

The soap:binding element MUST be present when using the SOAP binding.

<definitions .... > <binding .... > <soap:binding transport="uri"? style="rpc|document"?> </binding> </definitions>

The value of the style attribute is the default for the style attribute for each contained operation. If the style attribute is omitted, it is assumed to be "document". See section 3.4 for more information on the semantics of style.

The value of the required transport attribute indicates which transport of SOAP this binding corresponds to. The URI value http://schemas.xmlsoap.org/soap/http corresponds to the HTTP binding in the SOAP specification. Other URIs may be used here to indicate other transports (such as SMTP, FTP, etc.).

3.4 soap:operation

The soap:operation element provides information for the operation as a whole.

<definitions .... > <binding .... > <operation .... > <soap:operation soapAction="uri"? style="rpc|document"?>? </operation> </binding> </definitions>

The style attribute indicates whether the operation is RPC-oriented (messages containing parameters and return values) or document-oriented (message containing document(s)). This information may be used to select an appropriate programming model. The value of this attribute also affects the way in which the Body of the SOAP message is constructed, as explained in Section 3.5 below. If the attribute is not specified, it defaults to the value specified in the soap:binding element. If the soap:binding element does not specify a style, it is assumed to be "document".

The soapAction attribute specifies the value of the SOAPAction header for this operation. This URI value should be used directly as the value for the SOAPAction header; no attempt should be made to make a relative URI value absolute when making the request. For the HTTP protocol binding of SOAP, this is value required (it has no default value). For other SOAP protocol bindings, it MUST NOT be specified, and the soap:operation element MAY be omitted.

3.5 soap:body

The soap:body element specifies how the message parts appear inside the SOAP Body element.

The parts of a message may either be abstract type definitions, or concrete schema definitions. If abstract definitions, the types are serialized according to some set of rules defined by an encoding style. Each encoding style is identified using a list of URIs, as in the SOAP specification. Since some encoding styles such as the SOAP Encoding (http://schemas.xmlsoap.org/soap/encoding/) allow variation in the message format for a given set of abstract types, it is up to the reader of the message to understand all the format variations: "reader makes right". To avoid having to support all variations, a message may be defined concretely and then indicate it’s original encoding style (if any) as a hint. In this case, the writer of the message must conform exactly to the specified schema: "writer makes right".

The soap:body binding element provides information on how to assemble the different message parts inside the Body element of the SOAP message. The soap:body element is used in both RPC-oriented and document-oriented messages, but the style of the enclosing operation has important effects on how the Body section is structured:

  • If the operation style is rpc each part is a parameter or a return value and appears inside a wrapper element within the body (following Section 7.1 of the SOAP specification). The wrapper element is named identically to the operation name and its namespace is the value of the namespace attribute. Each message part (parameter) appears under the wrapper, represented by an accessor named identically to the corresponding parameter of the call. Parts are arranged in the same order as the parameters of the call.
  • If the operation style is document there are no additional wrappers, and the message parts appear directly under the SOAP Body element.

The same mechanisms are used to define the content of the Body and parameter accessor elements.

<definitions .... > <binding .... > <operation .... > <input> <soap:body parts="nmtokens"? use="literal|encoded"? encodingStyle="uri-list"? namespace="uri"?> </input> <output> <soap:body parts="nmtokens"? use="literal|encoded"? encodingStyle="uri-list"? namespace="uri"?> </output> </operation> </binding> </definitions>

The optional parts attribute of type nmtokens indicates which parts appear somewhere within the SOAP Body portion of the message (other parts of a message may appear in other portions of the message such as when SOAP is used in conjunction with the multipart/related MIME binding). If the parts attribute is omitted, then all parts defined by the message are assumed to be included in the SOAP Body portion.

The required use attribute indicates whether the message parts are encoded using some encoding rules, or whether the parts define the concrete schema of the message.

If use is encoded, then each message part references an abstract type using the type attribute. These abstract types are used to produce a concrete message by applying an encoding specified by the encodingStyle attribute. The part names, types and value of the namespace attribute are all inputs to the encoding, although the namespace attribute only applies to content not explicitly defined by the abstract types. If the referenced encoding style allows variations in it’s format (such as the SOAP encoding does), then all variations MUST be supported ("reader makes right").

If use is literal, then each part references a concrete schema definition using either the element or type attribute. In the first case, the element referenced by the part will appear directly under the Body element (for document style bindings) or under an accessor element named after the message part (in rpc style). In the second, the type referenced by the part becomes the schema type of the enclosing element (Body for document style or part accessor element for rpc style). For an example that illustrates defining the contents of a composite Body using a type, see section 2.3.1.  The value of the encodingStyle attribute MAY be used when the use is literal to indicate that the concrete format was derived using a particular encoding (such as the SOAP encoding), but that only the specified variation is supported ("writer makes right").

The value of the encodingStyle attribute is a list of URIs, each separated by a single space. The URI's represent encodings used within the message, in order from most restrictive to least restrictive (exactly like the encodingStyle attribute defined in the SOAP specification).

3.6 soap:fault

The soap:fault element specifies the contents of the contents of the SOAP Fault Details element. It is patterned after the soap:body element (see section 3.5).

<definitions .... > <binding .... > <operation .... > <fault>* <soap:fault name="nmtoken" use="literal|encoded" encodingStyle="uri-list"? namespace="uri"?> </fault> </operation> </binding> </definitions>

The name attribute relates the soap:fault to the wsdl:fault defined for the operation.

The fault message MUST have a single part. The use, encodingStyle and namespace attributes are all used in the same way as with soap:body (see section 3.5), only style="document" is assumed since faults do not contain parameters.

3.7 soap:header and soap:headerfault

The soap:header and soap:headerfault elements allows header to be defined that are transmitted inside the Header element of the SOAP Envelope. It is patterned after the soap:body element (see section 3.5).

It is not necessary to exhaustively list all headers that appear in the SOAP Envelope using soap:header. For example, extensions (see section 2.1.3) to WSDL may imply specific headers should be added to the actual payload and it is not required to list those headers here.

<definitions .... > <binding .... > <operation .... > <input> <soap:header message="qname" part="nmtoken" use="literal|encoded" encodingStyle="uri-list"? namespace="uri"?>* <soap:headerfault message="qname" part="nmtoken" use="literal|encoded" encodingStyle="uri-list"? namespace="uri"?/>* <soap:header> </input> <output> <soap:header message="qname" part="nmtoken" use="literal|encoded" encodingStyle="uri-list"? namespace="uri"?>* <soap:headerfault message="qname" part="nmtoken" use="literal|encoded" encodingStyle="uri-list"? namespace="uri"?/>* <soap:header> </output> </operation> </binding> </definitions>

The use, encodingStyle and namespace attributes are all used in the same way as with soap:body (see section 3.5), only style="document" is assumed since headers do not contain parameters.

Together, the message attribute (of type QName) and the part attribute (of type nmtoken) reference the message part that defines the header type. The schema referenced by the part MAY include definitions for the soap:actor and soap:mustUnderstand attributes if use="literal", but MUST NOT if use="encoded". The referenced message need not be the same as the message that defines the SOAP Body.

The optional headerfault elements which appear inside soap:header and have the same syntax as soap:header) allows specification of the header type(s) that are used to transmit error information pertaining to the header defined by the soap:header. The SOAP specification states that errors pertaining to headers must be returned in headers, and this mechanism allows specification of the format of such headers.

3.8 soap:address

The SOAP address binding is used to give a port an address (a URI). A port using the SOAP binding MUST specify exactly one address.  The URI scheme specified for the address must correspond to the transport specified by the soap:binding.

<definitions .... > <port .... > <binding .... > <soap:address location="uri"/> </binding> </port> </definitions>

4. HTTP GET & POST Binding

WSDL includes a binding for HTTP 1.1's GET and POST verbs in order to describe the interaction between a Web Browser and a web site. This allows applications other than Web Browsers to interact with the site. The following protocol specific information may be specified:

  • An indication that a binding uses HTTP GET or POST
  • An address for the port
  • A relative address for each operation (relative to the base address defined by the port)

4.1 HTTP GET/POST Examples

The following example shows three ports that are bound differently for a given port type.

If the values being passed are part1=1, part2=2, part3=3, the request format would be as follows for each port:

port1: GET, URL="http://example.com/o1/A1B2/3" port2: GET, URL="http://example.com/o1?p1=1&p2=2&p3=3 port3: POST, URL="http://example.com/o1", PAYLOAD="p1=1&p2=2&p3=3"

For each port, the response is either a GIF or a JPEG image.

Example 6. GET and FORM POST returning GIF or JPG

<definitions .... > <message name="m1"> <part name="part1" type="xsd:string"/> <part name="part2" type="xsd:int"/> <part name="part3" type="xsd:string"/> </message> <message name="m2"> <part name="image" type="xsd:binary"/> </message> <portType name="pt1"> <operation name="o1"> <input message="tns:m1"/> <output message="tns:m2"/> </operation> </portType> <service name="service1"> <port name="port1" binding="tns:b1"> <http:address location="http://example.com/"/> </port> <port name="port2" binding="tns:b2"> <http:address location="http://example.com/"/> </port> <port name="port3" binding="tns:b3"> <http:address location="http://example.com/"/> </port> </service> <binding name="b1" type="pt1"> <http:binding verb="GET"/> <operation name="o1"> <http:operation location="o1/A(part1)B(part2)/(part3)"/> <input> <http:urlReplacement/> </input> <output> <mime:content type="image/gif"/> <mime:content type="image/jpeg"/> </output> </operation> </binding> <binding name="b2" type="pt1"> <http:binding verb="GET"/> <operation name="o1"> <http:operation location="o1"/> <input> <http:urlEncoded/> </input> <output> <mime:content type="image/gif"/> <mime:content type="image/jpeg"/> </output> </operation> </binding> <binding name="b3" type="pt1"> <http:binding verb="POST"/> <operation name="o1"> <http:operation location="o1"/> <input> <mime:content type="application/x-www-form-urlencoded"/> </input> <output> <mime:content type="image/gif"/> <mime:content type="image/jpeg"/> </output> </operation> </binding> </definitions>

4.2 How the HTTP GET/POST Binding Extends WSDL

The HTTP GET/POST Binding extends WSDL with the following extension elements:

<definitions .... > <binding .... > <http:binding verb="nmtoken"/> <operation .... > <http:operation location="uri"/> <input .... > <-- mime elements --> </input> <output .... > <-- mime elements --> </output> </operation> </binding> <port .... > <http:address location="uri"/> </port> </definitions>

These elements are covered in the subsequent sections.

4.3 http:address

The location attribute specifies the base URI for the port. The value of the attribute is combined with the values of the location attribute of the http:operation binding element. See section 4.5 for more details.

4.4 http:binding

The http:binding element indicates that this binding uses the HTTP protocol.

<definitions .... > <binding .... > <http:binding verb="nmtoken"/> </binding> </definitions>

The value of the required verb attribute indicates the HTTP verb. Common values are GET or POST, but others may be used. Note that HTTP verbs are case sensitive.

4.5 http:operation

The location attribute specifies a relative URI for the operation. This URI is combined with the URI specified in the http:address element to form the full URI for the HTTP request. The URI value MUST be a relative URI.

<definitions .... > <binding .... > <operation .... > <http:operation location="uri"/> </operation> </binding> </definitions>

4.6 http:urlEncoded

The urlEncoded element indicates that all the message parts are encoded into the HTTP request URI using the standard URI-encoding rules (name1=value&name2=value…). The names of the parameters correspond to the names of the message parts. Each value contributed by the part is encoded using a name=value pair. This may be used with GET to specify URL encoding, or with POST to specify a FORM-POST. For GET, the "?" character is automatically appended as necessary.

<http:urlEncoded/>

For more information on the rules for URI-encoding parameters, see [5], [6], and [7].

4.7 http:urlReplacement

The http:urlReplacement element indicates that all the message parts are encoded into the HTTP request URI using a replacement algorithm:

  • The relative URI value of http:operation is searched for a set of search patterns.
  • The search occurs before the value of the http:operation is combined with the value of the location attribute from http:address.
  • There is one search pattern for each message part. The search pattern string is the name of the message part surrounded with parenthesis "(" and ")".
  • For each match, the value of the corresponding message part is substituted for the match at the location of the match.
  • Matches are performed before any values are replaced (replaced values do not trigger additional matches).

Message parts MUST NOT have repeating values.

<http:urlReplacement/>

5. MIME Binding

WSDL includes a way to bind abstract types to concrete messages in some MIME format. Bindings for the following MIME types are defined:

  • multipart/related
  • text/xml
  • application/x-www-form-urlencoded (the format used to submit a form in HTML)
  • Others (by specifying the MIME type string)

The set of defined MIME types is both large and evolving, so it is not a goal for WSDL to exhaustively define XML grammar for each MIME type. Nothing precludes additional grammar to be added to define additional MIME types as necessary. If a MIME type string is sufficient to describe the content, the mime element defined below can be used.

5.11 MIME Binding example

Example 7. Using multipart/related with SOAP

This example describes that a GetCompanyInfo SOAP 1.1 request may be sent to a StockQuote service via the SOAP 1.1 HTTP binding. The request takes a ticker symbol of type string. The response contains multiple parts encoded in the MIME format multipart/related: a SOAP Envelope containing the current stock price as a float, zero or more marketing literature documents in HTML format, and an optional company logo in either GIF or JPEG format.

<definitions .... > <types> <schema .... > <element name="GetCompanyInfo"> <complexType> <all> <element name="tickerSymbol " type="string"/> </all> </complexType> </element> <element name="GetCompanyInfoResult"> <complexType> <all> <element name="result" type="float"/> </all> </complexType> </element> <complexType name="ArrayOfBinary"> <complexContent> <restriction base="soapenc:Array"> <attribute ref="soapenc:arrayType" wsdl:arrayType="xsd:binary[]"/> </restriction> <complexContent> </complexType> </schema> </types> <message name="m1"> <part name="body" element="tns:GetCompanyInfo"/> </message> <message name="m2"> <part name="body" element="tns:GetCompanyInfoResult"/> <part name="docs" type="xsd:string"/> <part name="logo" type="tns:ArrayOfBinary"/> </message> <portType name="pt1"> <operation name="GetCompanyInfo"> <input message="m1"/> <output message="m2"/> </operation> </portType> <binding name="b1" type="tns:pt1"> <operation name="GetCompanyInfo"> <soap:operation soapAction="http://example.com/GetCompanyInfo"/> <input> <soap:body use="literal"/> </input> <output> <mime:multipartRelated> <mime:part> <soap:body parts="body" use="literal"/> </mime:part> <mime:part> <mime:content part="docs" type="text/html"/> </mime:part> <mime:part> <mime:content part="logo" type="image/gif"/> <mime:content part="logo" type="image/jpeg"/> </mime:part> </mime:multipartRelated> </output> </operation> </binding> <service name="CompanyInfoService"> <port name="CompanyInfoPort"binding="tns:b1"> <soap:address location="http://example.com/companyinfo"/> </port> </service> </definitions>

5.2 How the MIME Binding extends WSDL

The MIME Binding extends WSDL with the following extension elements:

<mime:content part="nmtoken"? type="string"?/> <mime:multipartRelated> <mime:part> * <-- mime element --> </mime:part> </mime:multipartRelated> <mime:mimeXml part="nmtoken"?/>

They are used at the following locations in WSDL:

<definitions .... > <binding .... > <operation .... > <input .... > <-- mime elements --> </input> <output .... > <-- mime elements --> </output> </operation> </binding> </definitions>

MIME elements appear under input and output to specify the MIME format. If multiple appear, they are considered to be alternatives.

5.3 mime:content

To avoid having to define a new element for every MIME format, the mime:content element may be used if there is no additional information to convey about the format other than its MIME type string.

<mime:content part="nmtoken"? type="string"?/>

The part attribute is used to specify the name of the message part. If the message has a single part, then the part attribute is optional. The type attribute contains the MIME type string. A type value has two portions, separated by a slash (/), either of which may be a wildcard (*). Not specifying the type attribute indicates that all MIME types are acceptable.

If the return format is XML, but the schema is not known ahead of time, the generic mime element can be used indicating text/xml:

<mime:content type="text/xml"/>

A wildcard (*) can be used to specify a family of mime types, for example all text types.

<mime:content type="text/*"/>

The following two examples both specify all mime types:

<mime:content type="*/*"/> <mime:content/>

5.4 mime:multipartRelated

The multipart/related MIME type aggregates an arbitrary set of MIME formatted parts into one message using the MIME type "multipart/related". The mime:multipartRelated element describes the concrete format of such a message:

<mime:multipartRelated> <mime:part> * <-- mime element --> </mime:part> </mime:multipartRelated>

The mime:part element describes each part of a multipart/related message. MIME elements appear within mime:part to specify the concrete MIME type for the part. If more than one MIME element appears inside a mime:part, they are alternatives.

5.5 soap:body

When using the MIME binding with SOAP requests, it is legal to use the soap:body element as a MIME element. It indicates the content type is "text/xml", and there is an enclosing SOAP Envelope.

5.6 mime:mimeXml

To specify XML payloads that are not SOAP compliant (do not have a SOAP Envelope), but do have a particular schema, the mime:mimeXml element may be used to specify that concrete schema. The part attribute refers to a message part defining the concrete schema of the root XML element. The part attribute MAY be omitted if the message has only a single part. The part references a concrete schema using the element attribute for simple parts or type attribute for composite parts (see section 2.3.1).

<mime:mimeXml part="nmtoken"?/>

6. References

[2] S. Bradner, "Key words for use in RFCs to Indicate Requirement Levels", RFC 2119, Harvard University, March 1997

[4] T. Berners-Lee, R. Fielding, L. Masinter, "Uniform Resource Identifiers (URI): Generic Syntax", RFC 2396

0 thoughts on “Transport Error Codes And Their Descriptive Essay

Leave a Reply

Your email address will not be published. Required fields are marked *